Apply DNL and UICONTROL to interface strings

You can help train the localization engine and improve the translation quality by applying DNL (do not localize) and UICONTROL (interface control) tags to terms in the Markdown source.

Apply DNL and UICONTROL before submitting a repo to the localization team. Using these tags does not require you to know whether your product is localized. However, understanding when and where to apply these tags is not always obvious. This page helps you understand how ExL uses these tags.

Special usage circumstances

All translatable content can accommodate localization tags, including:

However, you cannot apply tags to certain metadata values that otherwise must adhere to explicit syntax (in their corresponding YAML files). These metadata include role, type, level, solution, and so on (the ExL search filter tags).

Title and description metadata can use DNL and UICONTROL. However, for description metadata, you must place quotation marks around the entire description when it begins with a product name treated with DNL. Title metadata typically does not require DNL because product names (and the pipe shown in Google results) are added automatically.

For a table of contents file (TOC.md), no special guidelines exist. You can place DNL or UICONTROL in the link text of a TOC entry. For example [Configure Workfront with LDAP](administration-and-setup/add-users/configure-workfront-ldap.md).

You can use shortcuts to apply DNL and UICONTROL.

DNL guidelines

DNL is intended for branded product names (Adobe and third-party names) that always remain in English. It is not for interface controls and features (use UICONTROL for those).

Think of DNL when using names of applications that are advertised, purchased (have SKUs), and are installed.

DNL Syntax examples:

Do not use DNL on:

Use Code syntax for these information types.

The localization team is working on automating DNL. In the future, you will only need to verify that DNL was correctly applied.

UICONTROL

UICONTROL indicates an interface control (such as an option, field, tab, page, group of options, menu, or feature name in the UI).

Syntax examples

Apply UICONTROL only to explicit, exact references to interface elements (page names, options, fields, tabs, and so on). Most important, you should use bold with UICONTROL in navigation and procedures, where readers scan for instructions to make selections.

Note that you use bold only when user interaction action is required:

Do not include “>” or punctuation in UICONTROL. Wrap this element around the interface element name exactly as it displays in the product.

Markdown examples in steps:

1. On the Components page, select **Metrics** > **Page View**.

1. Select **Day** and drag it to the **Fallout** panel.

Markdown examples for using UICONTROL in paragraphs (where bold is not necessary):

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

In conceptual text, there’s no requirement for bold. However, you must capitalize the interface element and refer to them exactly how they display in the product.

Apply UICONTROL to features and clickable UI elements, especially in navigation and procedures.

How UICONTROL improves content

UICONTROL trains machine translation and helps human translators understand your documentation. The tag also conditionally preserves English so that documentation automatically localized on Experience League matches an interface available only in English.

You do not need UICONTROL in every situation in which you conceptually mention a feature name. For example, common terms like segment, trait, campaign, metric, or third-party cookie do not require UICONTROL when you are not explicitly referring to the interface.

Additional information about DNL and UICONTROL

What follows is additional information about these settings (if you’re interested)

HTML Example:

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

Using UICONTROL for an English UI

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 **File** > **Print**.

That syntax serves two purposes:

Usage examples:

Correct:

Incorrect:

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 UICONTROL-examples

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**.
1. In Workspace, click **Components** > **Segments**.
1. On the Segments page, click **Add**.
1. 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.

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

1. Click **Save**.

1. On Report Suite Manager, click **Edit Settings** > **General** > **General Account Settings**.
1. 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.
1. Click **Save**.

DNL and UICONTROL in metadata

You can add these tags to description and title metadata. If you begin a metadata field with a tag, you must encase the full description in quotation marks, or validation fails.

For example:

description: "Components in Analtyics enable you to create segments...."

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:

When not to use DNL or UICONTROL no-tags

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

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:

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 heading-test-case

Link test cases:

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 is 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:

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