{"title":"Working with translation files","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-work-with-translation-files/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-work-with-translation-files, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-work-with-translation-files","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to generate, maintain, and package XLIFF translation files for multilingual Business Central extensions, including namespace-aware IDs.","date":"2026-08-25","meta":{"topic":"concept-article"},"outline":[{"level":2,"title":"Generating the XLIFF file","slug":"generating-the-xliff-file","at":1039,"chars":4543},{"level":3,"title":"GenerateLockedTranslations","slug":"generatelockedtranslations","at":3342,"chars":404},{"level":3,"title":"Include namespaces in translation IDs","slug":"include-namespaces-in-translation-ids","at":3746,"chars":1836},{"level":2,"title":"Label syntax","slug":"label-syntax","at":5582,"chars":686},{"level":2,"title":"The XLIFF file","slug":"the-xliff-file","at":6268,"chars":1968},{"level":2,"title":"Translating other extensions","slug":"translating-other-extensions","at":8236,"chars":1955},{"level":3,"title":"Use the `<trans-unit id>` of the label where it was defined","slug":"use-the-trans-unit-id-of-the-label-where-it-was-defined","at":9269,"chars":922},{"level":2,"title":"Related information","slug":"related-information","at":10191,"chars":353}],"text":"Business Central is multi-language enabled, which means that you can display the user interface (UI) in different languages. In Business Central, this is done using XLIFF files, which is a standardized format used for computer-based translations.\n> IMPORTANT\n> We're announcing the deprecation of the Dynamics 365 Translation Service (DTS). This service will reach end-of-support on October 15, 2025, and will no longer be available after this date. For more information go https://learn.microsoft.com/dynamics365/fin-ops-core/fin-ops/get-started/removed-deprecated-features-platform-updates.\n> TIP\n> Optionally, use the Dynamics 365 Translation Service<https://learn.microsoft.com/dynamics365/fin-ops-core/dev-itpro/lifecycle-services/translation-service-overview> to get translations for your target languages. See Translate user interface files<https://learn.microsoft.com/dynamics365/fin-ops-core/dev-itpro/lifecycle-services/use-translation-service>.\nFor an overview of how translations are applied, see devenv-translations-overview.\n## Generating the XLIFF file\nTo add a new language to the extension that, you've built, first, you must enable the generation of XLIFF files. The XLIFF file extension is .xlf. The generated XLIFF file contains the strings that are specified in properties such as Caption, CaptionML, and Tooltip.\n> NOTE\n> To submit an app to Marketplace, you must use XLIFF translation files.\nIn the app.json file of your extension, add the following line:\n```json\n  \"features\": [ \"TranslationFile\" ]\n```\n> NOTE\n> If the Incremental Build setting is enabled in the AL Language extension configuration then all translations will be ignored, even though the `\"features\": [ \"TranslationFile\" ]` setting is specified in the app.json file. See AL Language Extension Configuration<devenv-al-extension-configuration>.\n> The same is true when using RAD publishing, all translations will also be ignored. See Work with Rapid Application Development<devenv-rad-publishing>.\nNow, when you run the build command (Ctrl+Shift+B) in Visual Studio Code, a `\\Translations` folder is generated and populated with the .xlf file that contains all the labels, label properties, and report labels that you're using in the extension. The generated .xlf file can now be translated.\n> IMPORTANT\n> The ML versions of properties are not included in the .xlf file:\n > properties/devenv-abouttitleml-property\n > properties/devenv-abouttextml-property\n > properties/devenv-captionml-property\n > properties/devenv-instructionaltextml-property\n > properties/devenv-optioncaptionml-property\n > properties/devenv-promotedactioncategoriesml-property\n > properties/devenv-requestfilterheadingml-property\n > properties/devenv-tooltipml-property\n> The methods-auto/textconst/textconst-data-type is not included in the .xlf file either.\n> IMPORTANT\n> Make sure to rename the translation file before building the extension next time, as it'll be overwritten.\nBy setting the GenerateCaptions flag in the app.json file, you specify that you want to generate captions based on the object name for pages, tables, reports, XMLports, and request pages. If the object already has a Caption property set, that value is used. For the table fields, the OptionCaption is used. The syntax is as follows:\n```json\n  \"features\": [ \"TranslationFile\", \"GenerateCaptions\" ]\n```\n### GenerateLockedTranslations\n> APPLIES TO: Business Central 2020 release wave 2 and later\nBy setting the GenerateLockedTranslations flag in the app.json file, you specify that you want to generate `<trans-unit>` elements for locked labels in the XLIFF file. The default behavior is that these elements aren't generated. See devenv-json-files.\n```json\n  \"features\": [ \"GenerateLockedTranslations\" ]\n```\n### Include namespaces in translation IDs\n> APPLIES TO: Business Central 2026 release wave 2 and later\nUse the TranslationsWithNamespaces compiler feature to include an object's devenv-namespaces-overview in generated translation IDs. The compiler also uses readable object, member, and property names instead of hashed values when the generated ID is 400 characters or fewer. Namespace-aware IDs prevent collisions between objects that have the same name in different namespaces. They also make translation entries easier to identify.\nThe feature requires runtime version 18.0 or later and the TranslationFile feature. See Choose runtime version in AL<devenv-choosing-runtime>. Add both features to the features setting in the app.json file:\n```json\n  \"features\": [ \"TranslationFile\", \"TranslationsWithNamespaces\" ]\n```\nFor example, the generated translation ID for a page caption changes from:\n```text\nPage 1066360047 - Property 2879900210\n```\nto:\n```text\nNamespace MyNamespace.MyProductArea - Page SamplePage - Property Caption\n```\nIf an object doesn't have a namespace, the compiler omits the namespace component but still uses readable names. If the readable ID would exceed 400 characters, the compiler generates a namespace-aware hashed ID instead.\nEnabling this feature changes the IDs in newly generated XLIFF files. The compiler can consume both legacy and namespace-aware IDs, so existing translation files remain valid.\nEnabling TranslationsWithNamespaces doesn't by itself trigger AppSourceCop rule AS0125. You can also add a namespace to an object that previously had none without triggering the rule if nothing else that affects its translation IDs changes. Moving a namespace, removing a namespace, or renaming an object or member are still breaking changes. See AppSourceCop Info AS0125<analyzers/appsourcecop-as0125>.\n## Label syntax\nThe following example shows the label syntax for the Caption property:\n```al\nCaption = 'Developer translation for %1', Comment = '%1 is extension name', Locked = false, MaxLength = 999;\n```\n> NOTE\n> The Comment, Locked, and MaxLength attributes are optional, and the order isn't enforced. See methods-auto/label/label-data-type.\nUse the same syntax for report labels:\n```al\nlabels\n{\n    LabelName = 'Label text', Comment = 'Context for the translator', MaxLength = 999, Locked = true;\n}\n```\nAnd the following is the syntax for Label data types:\n```al\nvar\n    GreetingLabel: Label 'Label text', Comment = 'Context for the translator', MaxLength = 999, Locked = true;\n```\n## The XLIFF file\nIn the generated .xlf file, you can see a `<source>` element for each label. For the translation, you need to add the `target-language` and a `<target>` element per label. Specify the `target-language` in the format `\"<language code>-<country code>\"`, such as `\"da-DK\"`, `\"es-ES\"`, or `\"de-DE\"`. The `<trans-unit id>` attribute identifies the object or object member that defines the text. Its format depends on whether you enable namespace-aware translation IDs<#include-namespaces-in-translation-ids>. This format is illustrated in the following example.\nThe following example uses the legacy translation ID format.\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<xliff version=\"1.2\" xmlns=\"urn:oasis:names:tc:xliff:document:1.2\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-transitional.xsd\">\n  <file datatype=\"xml\" source-language=\"en-US\" target-language=\"da-DK\" original=\"ALProject16\">\n    <body>\n      <group id=\"body\">\n        <trans-unit id=\"PageExtension 1716690578 - Property 2879900210\" maxWidth=\"999\" size-unit=\"char\" translate=\"yes\" xml:space=\"preserve\">\n          <source>Developer translation for %1</source>\n          <target>Udvikleroversættelse for %1</target>\n          <note from=\"Developer\" annotates=\"general\" priority=\"2\">%1 is extension name</note>\n          <note from=\"Xliff Generator\" annotates=\"general\" priority=\"3\">PageExtension - PageExtension</note>\n        </trans-unit>\n      </group>\n    </body>\n  </file>\n</xliff>\n```\n> NOTE\n> You can have only one .xlf file per language. If you translate your extension to multiple languages, you must have a translation file per language. There is no enforced naming on the file, but it's a good practice to name it `<extensionname>.<language>.xlf`.\nWhen the extension is built and published, you can change the language of Dynamics 365 Business Central to view the UI in the translated language.\n## Translating other extensions\nTo translate other extensions, for example, when adding translations to the Base Application, you must reference the project to be translated using the dependencies section in the app.json file. See devenv-json-files. When the dependencies are set, you can add xliff files in your current project that translates the object captions of the referenced extension. Create a directory named Translations, in the root of the extension, and place the translated xliff file there. When your extension is then built and published, change the language of Dynamics 365 Business Central to view the UI in the translated language.\n> NOTE\n> When translating other extensions, make sure that the attribute original in the `<file>` element in the xliff file is not set to the name of the current app. Otherwise, translations are only used to translate labels in the same app.\n> For apps where translations are meant to translate the current app, the generated xliff file will have the correct value of the app name.\n### Use the `<trans-unit id>` of the label where it was defined\nIn order to translate other apps, you must use the `<trans-unit id>` of the original property, not the one of an extension object as that might have been modified.\nThe following examples use the legacy translation ID format.\nIf MyPage is defined as:\n```al\npage 50000 MyPage\n{\n    Caption = 'Base Page';\n}\n```\nand it has `<trans-unit id>` for the page corresponding to `Page 2931038265 - Property 2879900210`.\nAnd if the following page extension of MyPage called MyPageExtension:\n```al\npageextension 50000 MyPageExtension extends MyPage\n{\n    Caption = 'Extension Page';\n}\n```\nhas `<trans-unit id>` for the page extension corresponding to `PageExtension 1716690578 - Property 2879900210`, then if you want to change the caption on the page, you must use the ID `Page 2931038265 - Property 2879900210`, which is the `<trans-unit id>` of the original property.\n## Related information\nWorking with labels<devenv-using-labels>\nWorking with multiple AL project folders within one workspace<devenv-multiroot-workspaces>\ndevenv-json-files\nTranslate user interface files using the Dynamics 365 Translation Service<https://learn.microsoft.com/dynamics365/fin-ops-core/dev-itpro/lifecycle-services/use-translation-service>"}