Localization best practices - UICONTROL and DNL

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.

How, why, and where to apply UICONTROL

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:

  • If the product is localized, the strings in UICONTROL are localized.
  • If the product is not localized, the strings remain in English.

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).

Example

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.

When to apply UICONTROL

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.

Guidelines

  • At a minimum, use UICONTROL in procedures where you document how to use the interface.
  • Apply bold to the UICONTROL in procedures when telling readers to “click” a specific option. This applies to a tab or to complete a certain field. (Examples below.)
  • Apply this tag only to the exact, formal interface element or feature name.
  • Leave out extra characters like punctuation or angle brackets (as part of navigation).
  • Do not apply UICONTROL to long sentences unless the UI element name is a long phrase or sentence. In that case, the control name might need to change in-product to something manageable.

For example:

example

(More syntax examples are shown below.)

Examples of UICONTROL syntax in procedures

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.]

example

NOTE

Make applying these elements easier by using keyboard shortcuts.

Other examples of UICONTROL and DNL

example

  • Acronyms: Do not apply UICONTROL (or DNL). (These are automatically left in English.)
  • Capitalization: Capitalize words in UICONTROL as you see them in the interface (interface elements are proper nouns and should be capitalized).
  • Generic icons: For certain feature names and UI elements, such as icons, use the name of the icon if it’s available (in hover text or tooltip). If no name is available, you might not know which term, if any, is specified in the translation database. Before you decide whether to tag such a term, keep in mind that if you tag it and no term is found, the term will remain in English in a machine translation. If your only option is pencil icon or edit icon, do not tag it. (Insert the icon as an inline image, then create a ticket for the developer to name the icon.)

Keep in mind that machine-translated content doesn’t need to be perfect.

Which Markdown content types can be tagged?

You can apply !UICONTROL and !DNL tags in nearly any component, including:

  • Paragraphs and lists
  • Headings
  • Links
  • Markdown tables (not HTML tables)
  • YAML metadata such a title/description
IMPORTANT

Do not use DNL or UICONTROL in HTML tables. See When not to use DNL or UICONTROL for more information.

When not to use DNL or UICONTROL

Do not add !UICONTROL and !DNL tags to the following components:

  • Code blocks - Everything in a code block remains in English, so there’s no reason to add [!UICONTROL] or [!DNL] unless you want that syntax to appear in the code block.
  • HTML tables - [!UICONTROL] and [!DNL] in HTML tables don’t work properly. Instead, use the <span class="uicontrol">term</span> format.
  • Acronyms

Available languages

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:

  • Analytics - FR, DE, JP, ES, BR, zh-Hans (Simplified Chinese), zh-Hant (T Chinese), KR
  • Target - FR, DE, JP, IT, ES, BR, zh-Hans, zh-Hant, KR
  • AEM - FR, DE, JP, IT, ES, BR, zh-Hans, zh-Hant, KR
  • Platform - FR, DE, JP
  • Campaign Classic - FR, DE, JP
  • Campaign Standard - FR, DE
  • Core Services - FR, DE, JP, IT, ES, BR, zh-Hans, zh-Hant, KR
  • Audience Manager - EN only
NOTE

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.

When to apply DNL

DNL is for:

  • Adobe Experience Cloud
  • Adobe Marketing Cloud
  • Adobe Advertising Cloud
  • Analytics, Target, Experience Manager, Audience Manager, and so on.
  • Product names

Guidelines:

  • Use DNL sparingly. If you’ve used it liberally on solution names, that’s okay. Leave them as is. If you wrapped words in DNL that should be UICONTROL, contact #sccm-assistance for 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.
  • No need to apply DNL to solutions pre-pended with Adobe. The MT is trained to leave Adobe Analytics, Adobe Target, Adobe Experience Manager, etc., in English.
  • Apply DNL to shortened, functional solution names in situations that might confuse readers and, likewise, the MT. These include: Analytics, Campaign, Target, Discover, Sky, and Recommendations.
  • Apply DNL to Boolean terms like AND or OR as such terms would confuse the MT engine.
  • Apply to third-party products like Mozilla Firefox.

Examples of potentially confusing sentences

example

HTML Example:

example

Headings:

The syntax works as expected.

example

Links:

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.)

example

Heading test case

Link test cases:

  • See Adobe(https://www.adobe.com)
  • See the Adobe website (bug - this will likely change)

Source:

example

Update the Do not Translate (DNT) file

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.

IMPORTANT

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.

When to use DONOTLOCALIZE

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.

NOTE

Code blocks (code) are not localized by default. There is no need to apply the DONOTLOCALIZE tag to either fenced or inline code blocks.

Example:

example

Keyboard shortcuts

If you need to tag lots of content for localization, consider creating keyboard shortcuts and using advanced find/change techniques.

Localization resources and glossaries

If you really want to dive into research to determine which terms are used in the database, the following localization resources are available:

Images and localization

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.

On this page