Transifex

  • Documentation
  • File formats
  • YAML

YAML

  • File extensions: .yaml, .yml
  • i18n type: YAML_GENERIC, YML

YAML is a human-friendly data serialization standard for a number of programming languages.

Transifex supports two types of YAML files:

  • Generic YAML files (YAML_GENERIC)
  • Rails-compatible YAML files which follow the i18n guidelines of Rails (YML)

When you upload a YAML file to Transifex, be sure to select the i18n type that corresponds with your YAML file.

Differences between the two types of YAML files

While the two types of YAML files share many commonalities, there are some important differences to call out.

  1. YAML files used for Rails must have a single root element denoting the file’s language code. The language code can follow one of several forms: xx, xx-XX, or xx_XX (e.g. en, en-US, or en_US). Generic YAML files don't require such a root element. They can follow any arbitrary but valid YAML structure.
  2. Plurals are handled differently. See the Plurals section below for more details.

Downloading YAML files

Transifex lets you download different versions, or modes, of a YAML file to match how you’ll be using the file:

  • For use: Get a file that only contains translated entries. 
  • Reviewed only: Get a file that only only contains reviewed entries.
  • For translation: Get a file that includes all entries, regardless of whether they're translated or not.

For all the modes above, comments from the original source file are included in the downloaded file.

There are additional modes available through the API. When using the onlytranslated and onlyreviewed modes, the translation file will include only the translated or reviewed strings — everything else from the original YAML file is removed. This means that comments, keys for untranslated/unreviewed strings, and keys with no translatable value will not be included.

Let’s say you upload the following source file:

en:
    key1: value1
    # This is a comment for key2.
    key2: value2
    # non translatable integer value
    key3: 123

And then you translate value1 and translate and review value2 for Greek (el). If you download the translation file for Greek using the onlytranslated mode, you'll get:

el:
    key1: value1 translation
    key2: value2 translation

And if you download the same file using the onlyreviewed mode, you will get:

el:
    key2: value2 translation

Now, let’s take a look at how Transifex handles different elements in YAML files.

How source string keys are determined

The unique source string key in a YAML file is created by going through the YAML structure from the root key to the specific string value and appending each key to the previous keys, with a . acting as a separator. When there's a list element, we use the list index surrounded by square brackets [ ] as the current key.

Let’s say you have the following source YAML file:

simple key: simple value
key:
  nested_key: nested value

# block sequence
key1:
  - list element 1
  - list element 2

# flow sequence
key2: ["list element 1", "list element 2"]

# nested sequences
key3:
  - key4:
    - el1
    - el2

This will produce the following key-string pairs:

[
{"simple key": "simple string"},
{"key.nested_key": "nested string"},
{"key1.[0]": "list element 1"},
{"key1.[1]": "list element 2"},
{"key2.[0]": "list element 1"},
{"key2.[1]": "list element 2"},
{"key3.[0].key4.[0]": "el1"},
{"key3.[0].key4.[1]": "el2"}
]

Tip

You can check the unique key for each string in the Context tab inside the Editor.

Comments

Valid YAML comments preceding an element are saved as a developer comment for the source string extracted from the element. These developer comments are shown to translators in the Editor. 

In the example below, the comment "This is a comment for Libraries" will be associated with the entry "Libraries.”

en:
    nav:
        # This is a comment for Libraries.
        libraries: 'Libraries'

Multi-line comments such as the one below are supported as well:

en:
    nav:
        # This is a comment for Libraries with
        # two lines.
        libraries: 'Libraries'

Indentation

Indentation in the original YAML file are detected and preserved in the translation files produced later. Transifex detects indentation by examining the first keys of your file so it’s best to keep the indentation in your YAML uniform.

# two spaces indentation
en:
  foo: …

# four spaces indentation
en:
    foo: …

Anchors(&) and aliases(*)

Anchors and aliases, which are denoted with the & and * symbols, respectively, allow you to reuse parts of a YAML structure. Aliases are ignored when found in the YAML document in order to not produce duplicate strings. Aliases and anchors are preserved in the translation file though.

For example, the following YAML snippet:

first_key: &label1
  - first element
  - second element
second_key: *label1

Won't be expanded into its equivalent:

first_key:
- first element
- second element
second_key:
- first element
- second element

because first element and second element will appear twice.

Only the following two strings will be in the Editor:

first element
second element

The downloaded file will look like this:

first_key: &label1
  - <translation for “first element”>
  - <translation for “second element”>
second_key: *label1

Note

Plurals support is only available for Rails-compatible YAML files.

For Rails-compatible YAML files, the different plural forms for the same string are grouped together.

If you had the following English source file:

en:
  less_than_x_minutes:
    one:   "less than a minute"
    other: "less than %{count} minutes"
  error_msg:
    one: "1 error"
    other: "%{count} errors"

There will be two strings in the Editor, each with two plural forms:

One: "less than a minute"
Other: "less than %{count} minutes"

One: "1 error"
Other: "%{count} errors"

Extra plural rule keys are allowed as long as all the required plural rules for the language are present.

Let's say you had the following snippet for the English, which only supports the "one" and "other" plural rules:

en:
  test_one:
    zero: Zero 
    one: one
    other: Other

The string in Transifex will be pluralized but the zero key will be ignored. Its value won't be visible in the Editor and will be excluded from the dowloaded file.

If a node contains extra keys that do not correspond to a valid plural rule, i.e. keys other than ["zero", "one", "two", "few", "many", "other"], the node won't be parsed as a pluralized string and each key will be parsed as a separate string, even if the required plural rules are there.

As an example, for this snippet:

en:
  players:
    random_key: 'random value'
    one: '%{count} player'
    other: '%{count} players'

the following strings will be available in the Editor:

random value
%{count} player
%{count} players

Generic YAML

For generic YAML files, no entry is treated as pluralized.

The same English source file from before will produce four separate strings in the Editor: 

less than a minute
less than %{count} minutes
1 error
%{count} errors

Literal and folded strings

Multiple line strings can be written either as a literal block using | or as a folded block using >. The style of these strings will be preserved in the translation file.

Literal strings

If you had this literal string:

literal_block: |
    This entire block of text will be the value of the 'literal_block' key,
    with line breaks preserved.

    The literal continues until de-dented and the leading indentation is
    removed.

        Any lines that are more indented will keep the rest of their indentation -
        these lines will be indented by 4 spaces.

It'll appear like this in the Editor as a single string:

This entire block of text will be the value of the 'literal_block' key,
with line breaks preserved.

The literal continues until de-dented, and the leading indentation is
stripped.

   Any lines that are 'more-indented' keep the rest of their indentation -
   these lines will be indented by 4 spaces.

Folded strings

If you had this folded string:

folded_block: >
    This entire block of text will be the value of the 'folded_style' key, but this
    time, all newlines will be replaced with a single space.

    Blank lines, like above, are converted to a newline character.

        More indented lines keep their newlines, too -
        this text will appear over two lines.

It'll appear like this in the Editor as a single string:

This entire block of text will be the value of the 'folded_style' key, but this time, all newlines will be replaced with a single space.

Quoted strings

Strings wrapped with single quotes or double quotes in your source file will keep the quotes in  the translation file unless this results in an invalid file. In that case, the quotes are replaced with a different style of quotes. Quotes are hidden in the Editor to make translation easier. 

This snippet:

single_quoted_string: ‘some value’
double_quoted_string: “another value”
plain_string: third value

Will produce the following three strings in Transifex:

some value
another value
third value

Sequences

Transifex treats each item in a sequence or list (denoted with a - at the beginning of a key) as a single string and hides list markers in the Editor. Both block and flow style sequences are treated the same.

This YAML snippet:

# block sequence
key1:
  - list element 1
  - list element 2

# flow sequence
key2: ["list element 1", "list element 2"]

# nested sequences
key3:
  - key4:
    - el1
    - el2
  - key5: some value

Produces the following seven strings in Transifex:

list element 1
list element 2
“list element 1”
“list element 2”
el1
el2
some value

Non-string

YAML supports numerous data types. Since it only makes sense to translate string-like values, Transifex will ignore int, float, symbols, variables and other non string and non-container (i.e. lists and mappings) data types when importing YAML files.

Tags

Nodes can specifically be typed, using YAML's built-in types or custom ones. Both YAML_GENERIC and YML parsers can handle any translatable content that is marked as a custom typed variable using tags. We store custom tags in context field in the editor. This information is preserved upon export, everytime you request the file back.

Example:

en:
  foo:  !test bar # Should treat as string and ignore leading spaces
  bar: !xml "foo <xml>bar</xml>" # Also a string
  hello: World # Translatable
  number: !!int 123 # Should ignore
  bin: !!binary aGVsbG8= # Should ignore

Under the context tab in the editor, the following information will be available:


yml_tags.png#asset:5423

Important note:

Custom tags are added back to the compiled files when one of the following download modes is used: default, reviewed, translator.

However, custom tags are not included in the compiled files, when one of the following download modes is used instead: onlyreviewed, onlytranslated