File extension(s) | .yaml, .yml |
i18n type(s) | YAML_GENERIC YML (Rails compatible) |
YAML is a human-friendly data serialization standard for several 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, 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, some crucial differences exist.
YAML files used for Rails must have a single root element denoting the file’s language code. The language code can follow 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.
Plurals are handled differently. Please take a look at 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 contains translated entries. All the entries that have yet to be translated will be returned empty.
Reviewed only: Get a file that contains reviewed entries. All the entries that have yet to be reviewed will be returned empty.
For translation: Get a file that includes all entries, regardless of whether they're translated.
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:
yaml
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 the following:
yaml
el:
key1: value1 translation
key2: value2 translation
And if you download the same file using the onlyreviewed mode, you will get the following:
yaml
el:
key2: value2 translation
Let’s 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:
yaml
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.”
yaml
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 is detected and preserved in later translation files. Transifex detects indentation by examining the first keys of your file, so it’s best to keep the indentation in your YAML uniform.
yaml
# two spaces indentation
en:
foo: …
# four spaces indentation
en:
foo: …
Anchors(&) and aliases(*)
Anchors and aliases, denoted with the & and * symbols, allow you to reuse parts of a YAML structure. Aliases are ignored when found in the YAML document so as not to produce duplicate strings. Aliases and anchors are preserved in the translation file, though.
For example, the following YAML snippet:
yaml
first_key: &label1
- first element
- second element
second_key: *label1
Won't be expanded into its equivalent:
yaml
first_key:
- first element
- second element
second_key:
- first element
- second element
Because the first element and the second element will appear twice.
Only the following two strings will be in the Editor:
yaml
first element
second element
The downloaded file will look like this:
yaml
first_key: &label1
- <translation for “first element”>
- <translation for “second element”>
second_key: *label1
Plurals
📝Note: Plurals support is only available for Rails-compatible YAML files.
The plural forms for the same string are grouped together for Rails-compatible YAML files.
If you had the following English source file:
yaml
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:
yaml
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 English, which only supports the "one" and "other" plural rules:
yaml
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 downloaded file.
Including the "zero" key in the source file will generate an error in Ruby on Rails when it tries to pluralize a string with an untranslated "zero" plural form.
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:
yaml
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:
yaml
less than a minute
less than %{count} minutes
1 error
%{count} errors
📝Note: Do you want to find out more about plurals in Transifex? Please check here.
Literal and folded strings
Multiple line strings can be written 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:
yaml
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:
yaml
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 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. Quotes are hidden in the Editor to make translation easier.
This snippet:
yaml
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:
yaml
# 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 values
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 be typed using YAML's built-in types or custom ones. The YAML_GENERIC and YML parser can handle any translatable content marked as a custom-typed variable using tags. These custom tags are stored in the context field within the editor. You can use alphanumeric characters and specific symbols (_ - : .) when naming custom tags. This information is preserved upon export every time 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:
📝Note: Custom tags are added back to the compiled files when one of the following download modes is used: default, reviewed, or translator.
However, custom tags are not included in the compiled files when one of the following download modes is used instead: onlyreviewed, onlytranslated.
Parser behavior
The following table outlines what occurs to strings when using the API, CLI, or UI to manipulate translation files depending on download mode.
📝 Note: Proofreading must be enabled for this logic to take effect. To learn how to enable proofreading, click here.
Default placeholders
These are the default placeholders that you could have in your file, and they will be recognized :
match: ['%1$s', '%(key1)s', '%s', '%d', '%.2f', '%-5d', '%+2d']
match: ['%{12}', '%{asdfg}', '%{1_2}', '%{ABCdef}']
Additional Information
💡Tip
Looking for more help? Get support from our Transifex Community Forum!
Find answers or post to get help from Transifex Support and our Community.