Applying DNL and UICONTROL to interface strings

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

• DNL = product name, do not localize.

  Syntax example: [!DNL Campaign]

• UICONTROL = an interface option, field, tab, page, group of options, or feature.

  Syntax example: [!UICONTROL File] menu.

The next two headings should be all you need to know about these tags. You can find deeper dive information after these sections if you want a deep dive and more examples.

DNL (do not localize)

This element preserves English on the tagged product names. Follow these guidelines:

• Apply DNL to branded product names that must remain in English.
• Do not apply DNL if the product name is in the DNT list (the product’s Do Not Translate database), or if you type the full name (pre-pended with Adobe). (These names should be in the DNT).
• If you shorten a product name (such as using Target instead of Adobe Target), apply DNL. This avoids confusion for product names with common different meanings.
• Do not apply DNL to file names, URLs, or code. (Use code syntax for those.)

UICONTROL (interface control)

This trains the machine translation and helps translators. The element also conditionally preserves English, so that localized documentation matches the English UI (if, for example, the application is not localized).

• Apply only to explicit, exact references to interface elements (page names, options, fields, tabs, and so on).

• Markdown examples for procedures:

  1. On the [!UICONTROL Components] page, select **[!UICONTROL Metrics]** > **[!UICONTROL Page View]**.

  1. Select **[!UICONTROL Day]** and drag it to the **[!UICONTROL Fallout]** panel.

• Markdown examples for using UICONTROL in paragraphs:

  The [!UICONTROL Components] menu includes [!UICONTROL Calculated Metrics], [!UICONTROL Segments], and [!UICONTROL Projects]. These features are available if you....

  Note that in regular text, there’s no need for bold. However, you must capitalize the interface element and refer to them exactly how they display in the product. When you generally refer to product features that are also common terms (such as segments, traits, metrics, reports, third-party cookies), no need for UICONTROL or formal treatment like capitalization.

See How, why, and where to apply UICONTROL (below) for more examples.

Deeper dive on DNL and UICONTROL

What follows is additional information about these settings, in case you need to know.

• [!DNL]: DNL means do not localize. Use DNL sparingly, almost never. Normally, product names are automatically left in English (if the strings exist in the DNT database).

  However, you must apply [!DNL] in potentially confusing situations. Use it on branded application names (both Adobe and always on third-party brands) if your reader might not know if you’re referring to Adobe’s product.

  Confusion can occur when describing functional branded names like Target and Analytics without Adobe. See When to apply DNL (below) for an important explanation.

• [!UICONTROL]: Apply to features and clickable UI elements, especially in navigation and procedures.

When to apply DNL

DNL forces the words to remain in English, and the only terms that qualify for DNL are formal, branded product names. (Adobe Analytics, Adobe Experience Manager, and so on.) These terms are in the product DNT and display in English automatically in docs.

Using functional product names generically, such as Target without Adobe, might cause the MT or customer to potentially not understand 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). Work with Amy Grace O’Brien to update the DNT.

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, code, or URLs. (Use code syntax.)
• You can add DNL to code blocks (inline or fenced), but it isn’t necessary. Code blocks are not localized. The DNL (and UICONTROL) syntax is stripped out of code blocks before the repo is packaged for publication.
• You can add DNL tags to HTML tables. The DNL/UICONTROL syntax is passed through to the localization repos but stripped out before packaging for publication.
• 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

These sentences properly use DNL to reduce confusion:

* Target specific geo-locations with [!DNL Target] by creating A/B tests.
* Adobe Analytics is a powerful application that collects analytics on your site. [!DNL 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, 1. Click Save), applying UICONTROL (with bold) 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:

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.

Guidance for applying UICONTROL

• Do not include “>” or punctuation in UICONTROL. Wrap this element around the interface element name exactly as it displays in the product.
• Do not use UICONTROL on file names.
• You can add UICONTROL to code blocks (inline or fenced), but it isn’t necessary. Code blocks are not localized. The UICONTROL (and DNL) syntax is stripped out of code blocks before the repo is packaged for publication.
• You can add UICONTROL tags to HTML tables. The UICONTROL/DNL syntax is passed through to the localization repos but stripped out before packaging for publication.
• 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:

• 1. Select **[!UICONTROL Open Editor]**.
• 1. Select **[!UICONTROL File]** > **[!UICONTROL Print]** > **[!UICONTROL Paper Size]**.

Incorrect:

• 1. Select the **[!UICONTROL Open Editor button.]**
• 1. Select **[!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 [!DNL Experience Cloud], then click **[!UICONTROL System Status]**.
1. In [!UICONTROL Admin Console], on the [!UICONTROL Users] page, click **[!UICONTROL Export CSV]**.
1. Click the **[!UICONTROL Setup]** tab, then complete the [!UICONTROL Email] field.
1. On the [!UICONTROL Setup] tab, click **[!UICONTROL Run]**.
1. Sign in to [!DNL Experience Cloud], then click **[!DNL Analytics]**.
1. In [!UICONTROL Workspace], click **[!UICONTROL Components]** > **[!UICONTROL Segments]**.
1. On the [!UICONTROL Segments] page, click **[!UICONTROL Add]**.
1. On the [!UICONTROL New Segment] page, complete the following fields:

    * **[!UICONTROL Title]**: Here you'd describe the Title field and apply !UICONTROL whenever you refer to it.
    * **[!UICONTROL Tags]**: Here you'd describe the Tags field.

1. Enable **[!UICONTROL Publish this segment to Experience Cloud]**.

    This field publishes this segment to the [!UICONTROL Audience Library] in [!DNL Experience Cloud], where you can use it in marketing activities in [!DNL Target] and other [!DNL Experience Cloud] applications.

1. Click **[!UICONTROL Save]**.

1. On [!UICONTROL Report Suite Manager], click **[!UICONTROL Edit Settings]** > **[!UICONTROL General]** > **[!UICONTROL General Account Settings]**.
1. Complete the following fields:
    * **[!UICONTROL Site title]**: Here you'd describe the Site title field and apply !UICONTROL whenever you refer to it.
    * **[!UICONTROL Base URL]**: Here you'd describe Base URL.
1. Click **[!UICONTROL Save]**.

Other examples of UICONTROL and DNL

• 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
• Tables (both Markdown and HTML)
• Metadata such a title/description

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

Localization tags in headings and links

Headings:

The syntax works as expected.

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

Heading test case

Link test cases:

• See [[!DNL Adobe]](https://www.adobe.com)
• See the Adobe website

Source:

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.

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.

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:

• Adobe Localization Resources home: https://adobe.sharepoint.com/sites/LocRes
• General terminology page: https://adobe.sharepoint.com/sites/LocRes/SitePages/Terminology-Management.aspx
• Place to see terminology: https://adobe.sharepoint.com/sites/LocRes/SitePages/Offline-TD-Export.aspx
  NOTE: At the bototm of this page are the actual offline exports. Each folder contains the Term Database, as well as the DNT list.
• Place for change requests: https://adobe.sharepoint.com/sites/LocRes/SitePages/TermChangeRequest.aspx

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.

Product terminology

Use this table to help determine whether a term is localized or remains in 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)