Applying DNL and UICONTROL to interface strings

To help improve the quality of localization, you can use the following two Markdown tags:

  • [!DNL]: DNL means do not localize. Use DNL sparingly. Normally, product names are automatically left in English. However, you must apply DNL to branded application names (both Adobe and third-party brands) when your reference to a product is potentially confusing. This issue occurs with functional branded names like Target and Analytics. See When to apply DNL (below) for an important explanation.
  • [!UICONTROL]: Apply to features and clickable UI elements, especially in navigation and procedures. See How, why, and where to apply UICONTROL (below) for examples.

Product terminology

Use this table to help determine whether a term is localized or remains in English.

Application DNL / UICONTROL Tag? English or Localized
Advertising Apply DNL if confusing English
Analytics Apply DNL if confusing English
Audience Manager None English
Experience Cloud None English
Experience Manager None English
Experience Platform None English
Experience Platform Data Add Adobe or DNL if confusing English
Experience Platform Content Add Adobe or DNL if confusing English
Campaign Add Adobe or DNL if confusing English
Commerce Add Adobe or DNL if confusing English
Customer Journey Analytics None English
Document Cloud None English
Journey Optimizer None English
Primetime None English
Real-Time Customer Data Platform None English
Target Add Adobe or DNL if confusing English
Marketo Engage None English
Sensei None English
Sign Add Adobe or DNL if confusing English

Core products & features by application

The following features and products were previously translated and now are to be left in English.

  • No UICONTROL required
  • Most are automatic in English, DNL tag not required
  • Some might need DNL tag where confusing (on functional, generic names). Use capitalization when referring to features or products.
  • Can leverage Acrolinx (coming soon)
Application Product/feature DNL guidance English or Localized
Analytics Analysis Workspace DNT English
Reports & Analytics DNT English
Ad Hoc Analysis DNT English
Data Connectors DNT English
Data Warehouse DNT English
Data Workbench DNT English
Federated Analytics DNT English
Report Builder DNT English
Tag Management DNT English
Audience Manager Identity Management DNT English
Audience Activation DNT English
Cross-device Measurement DNT English
Audience Marketplace DNT English
Audience Optimization DNT English
Campaign Campaign Management DNT English
Visual Cross-channel Orchestration DNT English
Integrated Customer Profile DNT English
Personalized Targeting DNT English
Centralized Offer Management DNT English
Real-time Interaction Management DNT English
Cross-channel Execution DNT English
Operational Reporting DNT English
Marketing Campaign Management DNT English
Experience Manager Sites DNL if confusing English
Assets DNL if confusing English
Mobile DNL if confusing English
Forms DNL if confusing English
Communities DNL if confusing English
Screens DNL if confusing English
Experience Platform Data DNL if confusing English
Content DNL if confusing English
Magento Commerce B2C & B2B commerce DNT English
Mobile Commerce DNT English
Segmentation & Personalization DNT English
Shipping & Fulfillment DNT English
Inventory Management DNT English
Order Management DNT English
Business Intelligence DNT English
Marketo Engage Lead Nurturing & Management DNT English
Account-Based Marketing DNT English
Personalization DNL if confusing English
Cross-Channel Engagement DNT English
Integrated Sales Applications DNT English
Marketing Measurement & Attribution DNT English
Target AB Testing DNT English
Multivariate Testing DNT English
Rules-Based Targeting DNT English
Geotargeting DNL if confusing English
Recommendations DNL if confusing English
Automated Personalization DNT English
Workfront Fusion DNL if confusing English
Goals DNL if confusing English
Scenario Planner DNL if confusing English

When to apply DNL

The DNL tag is for application and feature names that must always be in English. Using functional product names generically, such as Target without Adobe, causes the MT to not know your meaning. Or, it might incorrectly use a string in the translation memory. Using DNL or adding Adobe, ensures the strings remain in English.

If an application or core product name is in the DNT list, you do not need to apply DNL (do not localize).

Guidance for DNL

  • DNL is not for interface fields, options, controls, tabs, and so on, which are localized with the product. (Use UICONTROL for these.)
  • DNL is not intended for file names and code. Use code tags (inline or fenced) to preserve the English.
  • If you’ve used DNL too liberally (tagged 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, and more. Get help here because it’s preferable that you continue writing instead of retrofitting content.
  • No need to apply DNL to applications pre-pended with Adobe. The MT is trained to leave Adobe Analytics, Adobe Target, Adobe Experience Manager, and so on, in English.
  • Apply DNL mainly to confusing situations with shortened, functional application names. These names can 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 [!DNL Mozilla Firefox].

Examples of potentially confusing sentences

* With Target, you can create A/B tests to target specific geo-locations.
* Adobe Analytics is a powerful application that collects analytics on your site. Analytics can also help you with reporting to easily digest that data.

HTML Example:

<span class="dnl">Target</span>

How, why, and where to apply UICONTROL

Whenever you refer to a feature or interface control name (for example, "Click Save"), applying UICONTROL to the specific feature/option/field name benefits the reader. UICONTROL preserves English if the product is not available in the language in which the documentation was translated.

In the following example, the Analytics interface is not available in Italian. However, all the documentation is translated:

Example

In this scenario, the customer cannot follow the Italian interface instructions because UICONTROL was not applied to interface elements in Markdown.

Here’s the UICONTROL syntax, bolded in procedures:

1. Click **[!UICONTROL File]** > **[!UICONTROL Print]**.

That syntax serves two purposes:

  • Bolds the interface element for readability (so readers easily spot the path).
  • Instructs the machine (or human) translator to either leave the feature or interface name in English if the product has not been localized in the customer’s language. Or, translate the word if the product is translated.

Important: Do not use DNL in place of UICONTROL. Remember, DNL only applies to names that must remain in English in all languages, such as branded product names. UICONTROL is for words that conditionally need to remain in English, depending on product availability in a given language.

Requirements for applying UICONTROL

  • Your references to the interface element names and features must be exact matches.
  • 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.)
  • 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, you can discuss the interface name with Engineering and change it to something manageable.

Usage examples:

  • Correct: Click **[!UICONTROL Open Editor]**.

  • Incorrect: Click the **[!UICONTROL Open Editor button.]**

  • Correct: Click **[!UICONTROL File]** > **[!UICONTROL Print]** > **[!UICONTROL Paper Size]**.

  • Incorrect: Click **[!UICONTROL File > Print > Paper Size.]**

More syntax examples are shown below. There are technical exceptions described in When not to use DNL or UICONTROL.

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

1. Sign in to Experience Cloud, then click **System Status**.

1. In Admin Console, on the Users page, click **Export CSV**.

1. Click the **Setup** tab, then complete the Email field.

1. On the Setup tab, click **Run**.

1. Sign in to Experience Cloud, then click **Analytics**.
2. In Workspace, click **Components** > **Segments**.
3. On the Segments page, click **Add**.
4. On the New Segment page, complete the following fields:
    * **Title**: Here you'd describe the Title field and apply !UICONTROL whenever you refer to it.
    * **Tags**: Here you'd describe the Tags field.
5. Enable **Publish this segment to Experience Cloud**.
    This field publishes this segment to the Audience Library in Experience Cloud, where you can use it in marketing activities in Target and other Experience Cloud applications.
6. Click **Save**.

1. On Report Suite Manager, click **Edit Settings** > **General** > **General Account Settings**.
2. Complete the following fields:
    * **Site title**: Here you'd describe the Site title field and apply !UICONTROL whenever you refer to it.
    * **Base URL**: Here you'd describe Base URL.
3. Click **Save**.
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, the term will remain in English in a machine translation if no name is found. 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 UI languages

If you don’t know what languages are available for your product UI, 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 - FR, DE, JP, IT, ES, BR, zh-Hans, zh-Hant, KR
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.

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 [[!DNL Adobe]](https://www.adobe.com)
  • See the Adobe website

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