Extension .yml
Smartling identifier yaml
Example File yaml.yml
Resources Rails Internationalization

YAML files are often used in Ruby on Rails Localization. If you're localizing your Ruby on Rails app using YAML files, see Ruby on Rails Localization for important information.


Every string is created with variant metadata. The variant metadata is the full path of keys leading to the translatable string.

String Instructions

Smartling will automatically ingest and display file comments as instructions for translators. The comments must immediately precede the string. For example, for the following comment:

# Back button label
button: 'Back'

the text "Back button label" will be captured as a file instruction for the string 'Back'.

Specifying Paths

Some directives require you to specify a path or set of paths to keys or strings in the file. A path is a slash-separated string which uses Xpath-like syntax (although it's not Xpath.). The nodes separator is always / (slash).

Wildcards are allowed in path definitions.

For example, in the following path specifications:

[*/text, */string, system/log/text, system/log/text/details]

Smartling processes these paths as follows:

Other Information

Smartling supports plural translations when the original language strings use the Ruby on Rails i18n API's pluralization syntax. To avoid mistakenly ingesting strings as plurals because they happen to use the key name "one,other" etc., use the plurals_detection directive to turn detection off and then back on again.


Directive Format

# smartling.[directive_name] = [value]

The directive must be a single comment on one line, and there should not be any inline trailing symbols after the directive. Directives apply to all strings that follow them. Directives can be changed throughout the file


Values:1. Custom regular expression (pcre)
2. NONE - disable custom placeholders
Description:Used to define a custom placeholder format for strings in the file. See Placeholders in Resource Files for more information.
# smartling.placeholder_format_custom = \[.+?\]

Any characters surrounded by square brackets will be treated as a placeholder.


Description:Used to specify a standard placeholder format. See Placeholders in Resource Files for more information.
# smartling.placeholder_format = IOS

Specifies iOS-style placeholders for the file.


Values:on OR off

Enables or disables plurals detection.

Note: if using plural detection for a YAML file as part of a Ruby on Rails project, ensure your project is set up with correct pluralization rules.

# smartling.plurals_detection = on

Smartling will detect plurals in strings below this directive.


Description:ESCAPE_UNICODE indicates that all non-Latin1 (not in range 0000 - 007F of unicode) symbols after this comment should be escaped by a \uXXXX escaping expression in the process of a file download.
# smartling.download_format = ESCAPE_UNICODE

Hello? will be escaped as Hello\u1D25 on download.


Values:The value of this directive is expressed as [format]:[paths]

Specifies the format of strings for the specified paths and can enable HTML inside another file format.

Currently supported formats are:

  • HTML - string value will be parsed as HTML
  • @default - (note the leading at-sign) string value will be treated as simple text.

Separate multiple formats by commas

You may specify a single path for a format or a comma-separated list of paths enclosed in square brackets. The list may be empty.

# smartling.string_format_paths = html: *

Smartling parses values of all nodes as HTML.

# smartling.string_format_paths = html: */text

Smartling enables HTML in text nodes (and their subnodes), regardless of their parents.

# smartling.string_format_paths = html: [*/text, */string]

Smartling enables HTML in text and string nodes (and their subnodes), regardless of their parents

# smartling.string_format_paths = html: /product/description

Smartling enables HTML in /product/description and subnodes

# smartling.string_format_paths = html: */text, @default: /system/log/text

Smartling enables HTML in text nodes (and subnodes), but disables HTML in /system/log/text (and subnodes), as the exact match overrides the pattern match.

# smartling.string_format_paths =

Disables the effect of the previous string_format_paths instruction.


Values:int - 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:TRUE (default) or FALSE
Description:By default, if the first key in your YAML file matches a language code (e.g. 'en'), Smartling treats it as an i18n localization file and replaces it with the corresponding language code in translated files. See Ruby Localization for more information on this behavior. If you don't want this to happen, set this directive to false.
# smartling.yaml_locale_substitution = false

Prevents Smartling from substituting the first key in translated YAML files.


- (since Parser v3)
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