Manage languages and create translations for your digital media assets

Localization Service

Benefits & Purpose

When presenting video content in multiple countries or regions, one might immediately think of adding subtitles and/or audio dubbing (sometimes referred to as ‘subs and dubs’). While localizing the content itself is important, what’s often undervalued are the benefits of localizing the metadata associated with your content. Metadata refers to the descriptive information about each piece of content, including titles, descriptions, tags, images, and other contextual information. Localizing metadata for a streaming video service offers numerous benefits that enhance user experience, accessibility, and engagement on a global scale. Localizing your metadata involves more than just translation and entails adapting it to different languages, cultures, and regions.

Localization is often written in shorthand as L10n (the ‘10’ being used in lieu of the ten letters between l and n). Here are the key benefits of localizing metadata for your streaming video service:

  • Global Reach: By providing metadata in multiple languages, your streaming service can cater to a diverse audience around the world. This expands the reach and potential user base, leading to increased viewership and revenue opportunities.

  • User Engagement: Localized metadata makes content more accessible and relatable to users in different regions. This helps to capture their attention and encourages longer engagement with your platform, as viewers are more likely to watch and explore content that is presented to them in their native language.

  • Improved Search and Discovery: Localized metadata enhances the accuracy and effectiveness of search results and content recommendations. Your users can find relevant content more easily, leading to a smoother and more satisfying browsing experience.

  • Cultural Sensitivity: Different cultures have distinct sensitivities, taboos, and preferences. Localized metadata ensures that content descriptions, images, and titles are culturally appropriate and resonate positively with you users, avoiding potential misunderstandings or offense.

  • SEO and Discoverability: Localized metadata can boost your service’s search engine optimization (SEO) efforts, making it easier for users to find your content through online searches. This can boost the organic growth of your viewers.

  • Higher Conversion Rates: When users can access content in their preferred language, they are more likely to subscribe to a service, make purchases or watch longer.

  • Inclusivity: Localized metadata improves accessibility for non-native speakers and those who may struggle with selecting content presented in a foreign language. Such inclusivity can enhance your service’s reputation and user satisfaction.

  • Competitive Edge: In a competitive streaming landscape, offering localized metadata can set your service apart from other services that may not invest in such efforts. This can attract users who prioritize a tailored and user-friendly experience.

  • Data-Driven Insights: Localized metadata can provide valuable insights into user behavior and preferences across different regions. This data can inform you about content acquisition, production, and marketing strategies.

In summary, localizing the metadata for your streaming video service is a strategic move that benefits both you and your users. It enhances user engagement and discoverability, ultimately contributing to your platform’s growth and success in a global market.

L10n in Axinom Mosaic

Axinom Mosaic is an extremely flexible and versatile framework for video content management, with an open-source Media Service that allows you to define a data model around your business, as opposed to forcing you to adapt your business to some predefined schema. Axinom’s Localization Service is one of many managed services which are part of Axinom Mosaic’s suite of services.

Axinom’s Localization Service is a managed service to handle the translation and localization of entities from other services and does not depend on other services (besides core services). The Localization Service uses the concept of a ‘locale’ as opposed to a ‘language’ for your metadata, as ‘language’ alone might not allow for regional cultural differences. For example, the Portuguese language differs quite a bit between Brazil and Portugal, and folks from the UK might prefer this entire topic be referred to as localisation (also conveniently abbreviated as L10n). Although the Localization service is managed by Axinom, you have complete control to not only specify your default locale, but also to create and name your locales as you see fit. While we suggest using a standardized nomenclature, such as en-US or pt-BR, each of your locales also has a common name (such as American English, or Brazilian Portuguese) which you can set to whatever makes the most sense to your content management team.

Just as Axinom Mosaic’s Media Service allows you to define your own metadata schema, you can also determine which fields should be localizable. Some fields, such as ‘Original Title’ or an ID field probably should be presented consistently in all regions, while localizing fields such as Title, Synopsis, Genre, etc. will afford you the ability to tailor the presentation to your audience, either based on their geography or by user action within your UI. If you have distribution partners around the world, you can customize your data feeds to them to include the language(s) that are pertinent to their audiences.

The initial release of Axinom Mosaic’s Localization Service allows you to localize fields with textual representation. While this service is not intended to support the localization of assets (images/videos) and relations between entities, the metadata fields of those types can be translated - and the flexibility of Axinom Mosaic’s schema allows you to create a structure for your localized assets. An example might be creating image types of ‘Poster Image’ and ‘French Poster Image’ for a service based in the US which also serves a French-speaking audience in Canada. Videos support localization on the file level by providing different audio, subtitle, and closed caption streams (but only one video stream), which is separate from the localization of the metadata about the videos.

Some data that Axinom Mosaic’s Localization Service does support would best be localized directly in the end-user-facing service or the client application. Examples are deterministic unit conversions (e.g. from kilometers to miles) or very dynamic ones such as currency conversions based on the current exchange rate. Date and number formatting is left to the client application where the actual value does not change depending on the locale.

Over time, textual fields from all of Axinom Mosaic’s services (and well-integrated 3rd-party services) should be localizable. If there are any questions about the suitability of Axinom Mosaic’s Localization Service for your specific use case, please contact us and one of our experts would be happy to work with you.

Data Model

Localization ServiceEntityDefinitionsidserviceIdentityType - e.g. MovietitledescriptionisArchivedEntityFieldDefinitionsfieldNamefieldType - e.g. StringuiFieldType - e.g. TextareatitledescriptionsortIndexisArchivedEntityFieldValidationRulesfieldNametype - e.g. RegEx or UniqueseveritymessagessettingsLocalizationSourceEntitiesidtitleimageIdLocalizationSourceEntityFieldfieldNamefieldValueLocalizedEntitiesidrequiresLocalizationrequiresReviewLocaleslanguageTag - e.g. de or en-UStitleisDefaultstate - e.g. ActiveLocalizedEntityFieldfieldNamefieldValueFigure 1. Localization Service Data Model
Figure 1. Localization Service Data Model



The GraphQL API from the Localization Service provides read- and write access to the localization source data and the localizations.

To use the API you need a JWT from the Admin Service (see How to authenticate a service account).


The Localization Service supports several commands for starting actions on the Localization Service and events that you can react to. See also: Messaging.

If you want to localize some of your entity types like movies or episodes, you have to register those entities with their localizable fields in the Localization service. This is done by sending DeclareEntityDefinition or DeleteEntityDefinition commands. Corresponding finished or failed events are sent once the messages were processed in the Localization Service.

To send the data from the entity that you want to localize you can use the UpsertLocalizationSourceEntity and DeleteLocalizationSourceEntity commands, and to send the actual localizations, you can use the LocalizeEntity command. Corresponding finished or failed events are sent once the commands were processed in the Localization Service, but only if you specify an additional message context with the sent commands.

You can find more information on how to providing additional context to the message or extend your messaging in the Messaging page.


The user interface of the localization service provides a streamlined process for editors to efficiently localize content. Editors begin by selecting the desired locale they wish to localize entities for. This selection ensures that the content adjustments are tailored to the specific target audience.

locale selection
Figure 2. Locale Selection
You can have both Active and Inactive locales. Inactive locales can still be managed, but they will not be included during metadata validation and publishing. This can be helpful when introducing a new locale, adding localizations to existing entities when it is still inactive, and activating it only when all entities are localized and metadata for the new locale is ready to be published.

Once the locale is chosen, editors navigate to the explorer station. Here, they are presented with a comprehensive overview of localizable entities available within the chosen locale. The explorer offers convenient sorting and filtering options, enabling editors to quickly locate specific entities they intend to localize or review. This intuitive organization ensures a seamless experience in managing a variety of content elements.

localizable entity explorer
Figure 3. Localizable Entities Explorer

After identifying the desired entity for localization, editors proceed to the localization interface. In this interface, they are empowered to modify the values of the entity to accurately reflect the chosen locale’s nuances. Additionally, editors can also explore other localization options for the same entity across different locales, enhancing cross-locale consistency. This feature simplifies the process of maintaining uniform content across various regions while streamlining the localization workflow.

entity localization
Figure 4. Entity Localization

Catalog Service GraphQL API

It is important to note that you will not see anything localization-related in the GraphQL API and Schema of the Catalog Service. This is because to request the metadata for the specific locale, you have to pass a custom header with the request, e.g. "mosaic-locale": "de-DE". This approach ensures that adding (or removing) locales will not have an effect on the GraphQL API, meaning no need to explicitly update Client-facing frontend applications because the API got suddenly updated.

Hosting Service

When you deploy the Media service from the Hosting Service section in the Admin Portal, it will have the Localization service enabled by default, and will expect your environment to also have the Localization Service enabled. If you enable the Localization Service after the Media service deployment - there is a chance that you will not see any previously-created media items in the Localization workflows of your management system, but all newly created items will still end up there, providing an opportunity to test out Localizations functionality.

Should you perform a custom deployment of the media service, you are free to adjust the hosting manifest to either enable or disable the Localization functionality for the media service.