Preparing & Translating Supported File Types

Gettext PO/POT

Extension .po / .pot
Smartling Identifier gettext
Example File gettext.pot
Resources GNU Gettext Documentation 


Source Strings in Gettext files

Smartling ingests the field in msgid as the source string and returns the translation in msgstr.

For example, in a source file:

msgid “Hello world”
msgstr “”

"Hello world" is ingested as the source string.

Header Entries

If your Gettext file has a Header Entry, this can include a language field for the source locale of the file. When you download your translated file from Smartling, the language field will be rewritten to the target locale.


"Language: en\n"
"Language: es_PR\n"



Smartling can capture the msgctxt parameter as variant metadata for a string. For example:


msgctxt "Home Page Menu Navigation"
msgid "Home"
msgstr ""
msgctxt "Home Address Label"
msgid "Home"
msgstr ""

Will result in two strings for translation, both with the value “Home”. The translators can choose to to make the translation the same or not. The value of msgctxt displays to translators in the Translation Interface and the Smartling Dashboard. See the Help Center for more on translation variants.

String Instructions

Smartling includes comments in gettext files as instructions for translators. Comments follow the gettext standard. Only Extracted comments (beginning with #. ) are displayed to translators as instructions:


#. This is an instruction that is included in the file above a string.
#. This is also an instruction that will be presented to translators.
#: arch/linux/
msgid “Original source string.”
msgstr “”


Smartling automatically formats Gettext strings with HTML. No integration directive is required. Explicit HTML parsing can be turned on in order to create smaller source strings. Adding the smartling.string_format directive with the value html turns on HTML parsing. If this directive is present in the file Smartling explicitly parses all subsequent strings as HTML. With HTML parsing on, strings will be created based on HTML block elements. Strings that have no HTML are captured as normal. This directive is optional. Turning on HTML parsing behavior can result in smaller, more manageable strings, but will prevent you from being able to import existing translations. Translation imports are usually done as a one time action during account onboarding.  Please consult with Smartling if you are considering using this feature.


If you include a plural-forms header in a original uploaded file, Smartling will return the locale specific plural-forms header in the translated file.

For example if an English source file contains the following header:


"Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;\n"

A Russian translation file will contain:


"Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n"

Smartling supports the CLDR standards for plurals. For some languages, Gettext plural support differs from the CLDR standards. For example, CLDR allows four plural forms for Polish: one; few; many and other, while Gettext only supports one; few; and many. Smartling will allow translations for all four CLDR plural forms, but when downloading translated Gettext files, only those supported by Gettext will be included.

Return Untranslated Strings as Empty

When using file/get to download Gettext files from Smartling, the parameter includeOriginalStrings=false ensures that if no translations are available, Smartling returns an empty string. If the parameter is set to true, Smartling returns the original string.

Standard Placeholder Format

See Placeholders in Resource Files for more on placeholders.

Native Gettext Placeholder Formats

In addition to Smartling’s Placeholder Format directives, Smartling supports Gettext’s native method of declaring placeholder format using flags (comment lines beginning with #,). Flags affect only the entry they are part of. The following native Gettext placeholder types are supported:

  • #, c-format
  • #, java-format
  • #, ios-format
  • #, python-format
  • #, sh-format


File directives are supported, both inline and via our APIDirectives are specified in comments within the files, in the following format:

Inline File Format

# smartling.[directive_name] = [value] or [path]

API Parameter

smartling.[directive_name] = [value] 

Here are some examples of [directive_name], along with example values or paths.


Exact delivery depends on file type.

Values auto (default) | true | yes | false | no

Controls whether base characters ( > < & " ) are "escaped" into entities when delivering translations. This can be set universally for the whole file via API, or by setting the directive at the top/start of the file. The directive can also be placed inline to control the behavior of specific strings.

To use inline:
# smartling.entity_escaping = false

# smartling.entity_escaping = auto


For example, your translation might look like this:
This is an <hr> & " example string4

By default, using the "auto" setting, we will assume this is HTML from the <hr> tag.

When the translated file is downloaded, the translated string will be escaped as:
This is an <hr> &amp; &quot; example string4

Using # smartling.entity_escaping = false will allow This is an <hr> & " example string4 to appear unescaped.

XML Characters (always escaped)

Character (name) Escape sequence

< (less-than)


> (greater-than)


& (ampersand)


' (apostrophe or single quote)


" (double-quote)



Exact delivery depends on file type.


html4 (default)|html5



By default, all html4 entities are unescaped, except the basic set: &lt; &gt; &amp; &quot;.

When this directive is set to html5, all html5 entities will be unescaped as well.


# smartling.entity_escaping_type = html5 


Values propagate | none

Used to retain entity escaping for all non-base entities. For example normally we turn &copy; into © but if we use this new directive the translation will automatically update to use escaping from the source. For each entity character we'll check to see if it was escaped in the source and try to match (propagate) it in the target.

The default is none which is the current behavior, which recognizes HTML4 entities only - if HTML5 entities are required as well, you must use the entity_escaping_type=propagate directive.

propagate will only affect non-base entities - all named entities except &amp; , &quot;, &lt;, &gt; . Base entities continue to be controlled by HTML detection and the entity_escaping directive.

If the same character is both escaped and unescaped in the same string propagate will return the characters in the translation escaped in the same order as they were in the source. However, if there are a different number of characters in the translation where the translation process removed or added some and the escaping is inconsistent among them, propagate will escape all entities for that character.

This directive can be placed inline, in the API or in a template (consult your SA about configuring directive templates).

This does not affect source content at all - so using it will not result in new strings.

Numerical entities are not considered at all with this directive, and are treated normally.


To use inline:
# smartling.entity_escaping_strategy = propagate


Description  Used to specify a standard placeholder format. 

# smartling.placeholder_format = IOS

Specifies iOS-style placeholders for the file.




Values  1) Custom Java compatible regular expression.
2) NONE - disables any current custom placeholders 
Description  Specifies a custom placeholder format. Any text in your file matching the regular expression you provide will be captured as a placeholder. 

# smartling.placeholder_format_custom=\{([^}]+)\}

Any characters surrounded by curly brackets, e.g., {first name}, will be treated as a placeholder.

See Placeholders in Resource Files for more on placeholders.


Values html or NONE (default)

Control msgid level HTML parsing.  If this is set to HTML a single msgid can be ingested by Smartling as multiple strings, depending on block level tags. 

See Content Parsing for more information.

msgid "<div>String1 div1</div><div>String1 div2</div>"
msgstr ""

# smartling.string_format = html
msgid "<div>String2 div1</div><div>String2 div2</div>"
msgstr ""

# smartling.string_format = NONE
msgid "<div>String3 div1</div><div>String3 div2</div>"
msgstr ""

The first msgid gets the default behavior. One string is captured by Smartling:

<div>String1 div1</div><div>String1 div2</div>

and the CAT tool will allow the translator to manage the HTML tags, considered part of the translatable string.

The second msgid gets HTML parsed. Smartling captures two strings:

String2 div1
String2 div2

The third msgid returns to default parsing behavior. Smartling captures one string1:

<div>String3 div1</div><div>String3 div2</div>



Values  integer - Accepted values are 0 - 100 
Description  Sets the percentage by which original strings are inflated when downloading pseudo translations. If this directive is not set, pseudo translations are 30 percent longer than the original strings.’ 

# smartling.pseudo_inflation = 80

Downloaded pseudo translations will increase the length of original strings by 80 percent.




Values  translate OR notranslate 
Description  Use this directive to enable or disable processing of translation strings in the file. You must turn translation back on after the strings you want to exclude. 

# smartling.sltrans = notranslate

Strings below this directive will be captured as strings but excluded from translation.

# smartling.sltrans = translate

Strings below this directive will be translated.





on|yes|true or off|no|false or leading|trailing

The default value is on


A whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character is not a visible mark, but does occupy an area or space on a page.

Although whitespaces are necessary within a string (typically to separate words), unnecessary whitespaces can be found at the start of a string (leading) and at the end of a string (trailing).

With this directive, you can trim whitespaces, as it enables or disables whitespace trim management for the ingested strings.

By default, the leading and trailing whitespaces are trimmed.

You can choose to disable trimming or specify trimming for leading or trailing whitespaces.

The directive can be used inline or as the API request parameter.


# smartling.whitespace_trim=on

Smartling will trim leading and trailing whitespaces (default)

# smartling.whitespace_trim=off

Smartling will not trim leading or trailing whitespaces

# smartling.whitespace_trim=leading

Smartling will trim only leading whitespaces

# smartling.whitespace_trim=trailing

Smartling will trim only trailing whitespaces

Was this article helpful?