HTML

The Translate Toolkit is able to process HTML files using the html2po converter.

Conformance

• Can identify almost all HTML elements and attributes that are localisable.

• The localisable and localised text in the PO/POT files is fragments of HTML. Therefore, reserved characters must be represented by HTML entities:

  • Content from HTML elements uses the HTML entities & (&), < (<), and > (>).

  • Content from HTML attributes uses the HTML entities " (") or ' (').

• Leading and trailing tags are removed from the localisable text, but only in matching pairs.

• Can cope with embedded PHP, as long as the documents remain valid HTML. If you place PHP code inside HTML attributes, you need to make sure that the PHP doesn't contain special characters that interfere with the HTML.

Ignoring Content from Translation

Two methods are available to exclude specific content from translation:

1. data-translate-ignore attribute

   Any HTML element with the data-translate-ignore attribute will have its content and all nested elements excluded from extraction.

   <p>This will be translated</p>
   <div data-translate-ignore>
       <p>This won't be translated</p>
       <p>Neither will this</p>
   </div>
   <p>This will be translated again</p>
   

   This is useful for:

   • Legal disclaimers that must remain in original language

   • Code examples or technical content

   • Brand names and trademarks

   • Copyright notices

2. translate:off/on comment directives

   Content between <!-- translate:off --> and <!-- translate:on --> HTML comments will be excluded from extraction.

   <p>This will be translated</p>
   <!-- translate:off -->
   <div class="technical-content">
       <p>Technical documentation in English</p>
       <code>function example() { return "code"; }</code>
   </div>
   <!-- translate:on -->
   <p>This will be translated</p>
   

   This is useful for:

   • Temporarily disabling translation for sections during development

   • Excluding large blocks without modifying HTML attributes

   • Working with generated HTML where attributes can't be easily added

Both methods work with html2po extraction and po2html conversion, preserving ignored content in the original language.

Adding Translator Comment

Translators often need additional context to provide accurate translations. The Translate Toolkit supports adding translator comments using the data-translate-comment HTML5 data attribute.

data-translate-comment attribute

Any HTML element can have a data-translate-comment attribute to provide context for translators. These comments are extracted as automatic comments (marked with #.) when using the --keepcomments option with html2po.

<h1 data-translate-comment="This is the first text that is displayed">Hello world!</h1>
<p data-translate-comment="Welcome message for visitors">Welcome to our site!</p>
<button data-translate-comment="Primary call-to-action button">Sign Up Now</button>

When extracted with html2po --keepcomments, these generate PO files like:

#. This is the first text that is displayed
#: example.html+h1:1-1
msgid "Hello world!"
msgstr ""

#. Welcome message for visitors
#: example.html+p:2-1
msgid "Welcome to our site!"
msgstr ""

#. Primary call-to-action button
#: example.html+button:3-1
msgid "Sign Up Now"
msgstr ""

This is useful for:

• Explaining character limits or formatting requirements

• Providing UI context (e.g., "Button text", "Error message")

• Clarifying ambiguous terms or technical jargon

• Indicating target audience or tone

• Documenting brand names that should not be translated

The data-translate-comment attribute works alongside regular HTML comments (<!-- comment -->). Both are extracted and combined when using --keepcomments, giving translators comprehensive context.

Note

The data-translate-comment attribute uses the HTML5 data-* attribute specification, which is designed for custom data that doesn't affect rendering. This means your HTML remains valid and the attributes are safely ignored by browsers.

Message Context (Disambiguation)

Sometimes the same source string needs different translations depending on where it appears (e.g. "Open" as a verb vs. noun). You can disambiguate such cases using the data-translate-context attribute. Its value becomes the msgctxt in the generated PO file, allowing separate translations for the same msgid, without the excessively differentiated contexts from automated context disambiguation.

If an element does not specify data-translate-context, the following fallbacks apply when disambiguated contexts are needed due to duplicate source strings:

• {filename}:{element_id} when the element has an id attribute

• {filename}+{ancestor_id}.{relative_tag_path}:{line}-{column} when the element

  does not have an id but is a descendant of an element with an id. The relative_tag_path is the dot-separated tag path from the ancestor to the element. line/column come from the element's source location.

<p data-translate-context="verb">Open</p>
<p data-translate-context="noun">Open</p>

After extraction with html2po the PO will contain two distinct entries:

msgctxt "verb"
msgid "Open"
msgstr ""

msgctxt "noun"
msgid "Open"
msgstr ""

Translatable Meta Tags

The HTML converter automatically extracts content from meta tags that are suitable for translation, including social media meta tags used by platforms like Facebook, Twitter, and LinkedIn.

Standard Meta Tags

• <meta name="description" content="..."> - Page description

• <meta name="keywords" content="..."> - Keywords

Open Graph Meta Tags (for Facebook, LinkedIn, etc.)

• <meta property="og:title" content="..."> - Page title for social sharing

• <meta property="og:description" content="..."> - Page description for social sharing

• <meta property="og:site_name" content="..."> - Site name

Twitter Card Meta Tags

• <meta name="twitter:title" content="..."> - Page title for Twitter cards

• <meta name="twitter:description" content="..."> - Page description for Twitter cards

Non-Translatable Meta Tags

The following meta tags are intentionally not extracted for translation as they contain URLs, images, or technical values:

• og:url, og:image, og:type - URLs and content types

• twitter:card, twitter:image, twitter:site - Technical settings and URLs

• viewport, charset, http-equiv - Technical HTML settings

Example

<head>
    <meta name="description" content="Learn about our products">
    <meta property="og:title" content="Our Amazing Products">
    <meta property="og:description" content="Discover quality products">
    <meta property="og:image" content="https://example.com/image.jpg">
    <meta name="twitter:title" content="Our Amazing Products">
</head>

When extracted with html2po, the translatable strings will be:

• "Learn about our products"

• "Our Amazing Products"

• "Discover quality products"

The og:image URL is preserved as-is and not extracted for translation.

After translation with po2html, social media platforms will display the translated title and description when users share links to your website.

References

• Reserved characters

• Using character entities