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.
This element preserves English on the tagged product names. Follow these guidelines:
DNL
to branded product names that must remain in English.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).DNL
. This avoids confusion for product names with common different meanings.DNL
to file names, URLs, or code. (Use code syntax for those.)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.
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.
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
#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.[!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>
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:
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.
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.
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]**.
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 !UICONTROL
and !DNL
tags in nearly any component, including:
Do not add !UICONTROL
and !DNL
tags to the following components:
[!UICONTROL]
or [!DNL]
unless you want that syntax to appear in the code block.[!UICONTROL]
and [!DNL]
in HTML tables don’t work properly. Instead, use the <span class="uicontrol">term</span>
format.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:
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.
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.)
Link test cases:
[[!DNL Adobe]](https://www.adobe.com)
Source:
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.
Example:
If you need to tag lots of content for localization, consider creating keyboard shortcuts and using advanced find/change techniques.
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.
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 |
The following features and products were previously translated and now are to be left in English.
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 | |
Adobe Commerce (and Magento Open Source) | B2C & B2B commerce | DNT | English |
Segmentation & Personalization | DNT | English | |
Shipping & Fulfillment | DNT | English | |
Inventory Management | DNT | English | |
Order Management | DNT | English | |
Business Intelligence | DNT | English | |
Product Recommendations | DNT | English | |
Live Search | DNT | English | |
Payment Services | DNT | English | |
Amazon Sales Channel | 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 |