Using HTML Syntax to Prepare Phrases

Easy steps to improve your integration.

Save time by prepping your content for localization and translations. This guide explains how you can use HTML syntax to better prepare your content to quickly approve phrases and translate them.


Variables are a means of wrapping dynamic content for deduplication purposes. For example, you might consider using this for usernames or numeric amounts (like dates & currency). To create a variable, wrap the text in <var> tags.

Welcome back, <var>theC00lkid</var>.

If you don't use a <var> tag for something like the example above, then you could potentially get many similar copies of the same phrase, with a different name in each phrase, like:

Welcome back, theC00lkid.
Welcome back, Billy.
Welcome back, Edward.
Welcome back, Miriam.


Define Variables in the Localize Dashboard

You can now define most variables right in the Localize dashboard without modifying your code! Check out what's possible in the help doc for Define Variables in Your Dynamic Phrases.

There are still some circumstances that will still require you to add variables to your code, as detailed in that help doc.

Naming Variables

Naming variables helps translators to better understand the context of your phrases, so provide a name in the <var> tag.

Welcome back, <var username>theC00lkid</var>.



  • <var> is a valid HTML5 tag that behaves similarly to a <span> tag.
  • Since HTML attributes are case-insensitive, a variable name of userName and username are the same, and Localize will use the all lowercase version of the variable name.


Adding a pluralize attribute to the variable indicates to our system whether the phrase should be singular or plural. This is especially important for languages like Arabic.

You have <var count pluralize="1">one</var> notification.

The value of the pluralize attribute must be set to an integer denoting the number of items represented by the variable. To improve the accuracy of pluralization, we recommend manually inputting the singular and plural versions of your phrases on your Localize dashboard. You'll be prompted to do this if you use plural phrases in your app, as seen here:

When you click the "Click here" link you'll be presented with the following dialog, in which you can enter the singular and plural versions of the source phrase.

Attribute: isolate

Localize will intelligently group together adjacent text in your app. If you notice an inaccurate grouping, you may define one yourself by adding an empty isolate attribute to the parent element.

Combine Example: If you see that Localize is separating something that you think should be kept together, you can add an isolate attribute in the parent HTML element and Localize will bring that in as one phrase.

<div isolate>Here's a phrase <b>that has some bold text</b> in it that we want to keep as one phrase in Localize.</div>

This will bring this into your dashboard as one phrase: "Here's a phrase {{1}}that has some bold text{{/1}} in it that we want to keep as one phrase in Localize.".

Separate Example: Localize will group adjacent text nodes and link elements together to form one text segment. In the example below, we can add an isolate attribute to ensure each link is parsed as its own phrase.

Website navigation: 
<a href="/" isolate>Home</a>
<a href="/about" isolate>About</a>

Doing this will create 2 phrases in your Localize dashboard: "Home" and "About".


Can't Group a Whole Page

The isolate tags will not work when attempting to group entire pages. The isolate tags are for grouping smaller paragraph length amounts of content.

Attribute: notranslate or translate="no"

Adding an empty notranslate (or translate="no") attribute to an element prevents it and all of its child elements from being brought into the Localize dashboard, so it will not appear as a pending phrase. It also prevents the element from being grouped with adjacent text.

<div notranslate>This phrase won't be brought into the dashboard, and it won't be a pending phrase.</div>
<div translate="no">Neither will this.</div>


notranslate value ignored

Setting the value of the notranslate attribute will be ignored. Localize assumes that if the notranslate attribute is present, then we won't bring that phrase into your dashboard.

So the following examples all work the same:

  • Some content
  • Some content
  • Some content

The same goes if you use the data-notranslate form of this attribute.


Won't work in the HTML Element

Note that adding notranslate to the element in the page will NOT stop Localize from bringing in content from the page.

Attribute: ignore

Adding an empty ignore attribute to an element will ignore the content of the element while allowing it to be grouped with adjacent text. This can be useful to prevent translating names, or words such as "Tweet".

For example:

This website is called <span ignore>Localize</span>.

The above phrase will be detected and available to translate as: This website is called {1}{/1}.

Note: <code>, <var>, and <kbd> elements are automatically ignored.

Attribute: aria-label

Localize supports the aria-label attribute for improved accessibility. The aria-label attribute is used to define a string for HTML elements which don't have visible text on the screen. This allows screen readers (or other assistive technology) to give context to HTML elements. Localize will pull these strings into your dashboard so that they may be translated.

For example:

<button onclick="modalDialog.close()" aria-label="Close the Dialog">X</button>

A screen reader would read the text "Close the dialog" (or the translated version if in a target language) when it encountered this button element.

Attribute: title

Localize supports the title attribute. You can use the title attribute to specify extra information about any HTML element. This extra information is most often shown as a tooltip when hovering over the element, but is also used by screen readers and other assistive technologies to improve accessibility. Localize will pull these strings into your dashboard so that they may be translated.

For example:

<p title="Great localization tools"></p>

The text "Great localization tools" would appear as a tooltip when the user hovers over the HTML element, and a screen reader would read the text "Great localization tools" (or the translated version if in a target language) when it encountered this button element.

Adding Labels to your Phrases

You can add Labels to your phrases in the HTML of your site by adding a data-localize attribute. Read how to do this in our Labels documentation.

This will make it easier to categorize content and find it later in your Localize dashboard.

Variable with Data prefix

We support implementation with the “data-“ prefix. For example: “data-var” and “data-pluralize”.

I have <var data-var="num" data-pluralize="2">2</var> dogs.

Naming variables with “data-var” is optional. The variable name can provide more context to translators.

Updated 2 months ago

Using HTML Syntax to Prepare Phrases

Easy steps to improve your integration.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.