All of our Markdown help content is localized initially using machine translation (MT). Depending on the page, we might perform human translation (HT), even if the content has not been previously localized. (For an overview of the localization workflow, see Localization overview.)
To help improve the quality of localization, you can use the following two Markdown tags:
[!UICONTROL]:Apply to clickable UI elements, especially in procedures. See How, why, and where to apply UICONTROL (below) for examples.
[!DNL]:Apply to trademark product names. These include Adobe solution names and third-party product names that must remain in English. Use in limited situations. See When to apply DNL (below) for an explanation.
The UICONTROL tag instructs the MT to leave the feature or interface name in English if the product has not been localized in the customer’s language. This enables a customer to read localized documentation while using an English interface. Therefore:
In the following screenshot of a French documentation page, assume that the interface is not available in French. However, customers see English feature or interface control names (circled).
That screenshot indicates that Configuration and Console Web were wrapped with UICONTROL. The system did not translate those words, so now they match what the reader sees in the interface. This approach is helpful for readers trying to follow steps in a procedure containing navigation and instructions about which fields or options to configure.
Whenever you generally refer to a feature or interface control name, applying UICONTROL benefits the reader. (There are technical exceptions described in When not to use DNL or UICONTROL.) For example, if you are describing Analysis Workspace, or a metric name in the product, apply UICONTROL. Those names are translated with the interface. UICONTROL ensures that those words are translated in your documentation to match the UI.
(More syntax examples are shown below.)
The following example shows isolated steps and multiple steps. It shows various syntax situations for applying UICONTROL. They include when to use bold, how to use UICONTROL when referring to tabs, fields, navigation, and clickable options.
[Editor’s note: If you’re new to technical writing, the following example also shows various ways to correctly write a typical command step or series of steps. Learn when to use on versus in, and how to refer to a product, page, or tab. Use sign-in instead of log-in and learn how to document a menu, fields, and options.]
Make applying these elements easier by using keyboard shortcuts.
Keep in mind that machine-translated content doesn’t need to be perfect.
You can apply
!DNL tags in nearly any component, including:
Do not use DNL or UICONTROL in HTML tables. See When not to use DNL or UICONTROL for more information.
Do not add
!DNL tags to the following components:
[!DNL]unless you want that syntax to appear in the code block.
[!DNL]in HTML tables don’t work properly. Instead, use the
If you don’t know what languages are available for your product, you can ask the IEM. Here are the current solutions and available languages:
Of the three tagging options described on this page, UICONTROL is the most crucial for delivering high-quality translation. Consider UICONTROL to be mandatory in procedures. However, it is understood that, at times, you might not apply it perfectly. Just do your best. You can always go back and make corrections.
DNL is for:
#sccm-assistancefor a regular expression that lets you easily search and replace DNL with UICONTROL. SCCM can help you retrofit these as well. It’s preferable that you continue writing instead of retrofitting content.
Examples of potentially confusing sentences
The syntax works as expected.
For links, the syntax does not work as expected. It’s necessary to remove the tag brackets within the link text to prevent the brackets from appearing in the link. (Note that this behavior might change at some point.)
Link test cases:
We have a DNT file that you can update with words you want to leave in English by default. Formal, long solution names like Adobe Analytics, Adobe Campaign, and Adobe Target are on the list.
If a term is added to the DNT list, it applies to all languages and all products. Add the term only if you are 100% certain that it fits these criteria. Also, there is a lag between when the term is added to the DNT list and when the engine is trained on that new list. (Also, training the list can be expensive.)
Follow the instructions on updating the DNT list to get started.
This element is not often used. Sometimes, we need to flag certain sections of content within an article to be English only. For sections of text that should not be localized, use the
[!DONOTLOCALIZE] extension and use block quotes ( > ) to mark the entire English-only section. The content after the DONOTLOCALIZE block will be localized when the file is submitted.
Code blocks (
code) are not localized by default. There is no need to apply the DONOTLOCALIZE tag to either fenced or inline code blocks.
If you really want to dive into research to determine which terms are used in the database, the following localization resources are available:
For images that should not be localized, create a separate
do-not-localize folder in the assets folder. Typically, images without text or images containing only sample content would be placed there. This removes any “noise” from the assets folder and reduces the amount of questions.
We also recommend that you remove any assets that you’re not referencing and don’t plan to reference. Maintaining clean asset folders helps the Localization team avoid unnecessary work.