Preparing Content for Translation

YAML

 

Extension .yaml
Smartling Identifier yaml
Example File (see below for example)
Resources YAML ("official" site)

When downloading translated YAML files via the Files API, setting the parameter includeOriginalStrings=false will strip untranslated elements (key and value) from the file.

Smartling delivers the values of mappings that have been translated by Smartling in the Double Quoted Scalar style. This is done to insure that the translation can contain any character entered by the translator. All values are double quoted regardless of their actual value.

YAML file example:

---
negative: "No"
positive: "Yes"
access_denied: "Access denied"
account: "Account: %s"
account: "Page #%d"
action: "Action"
actions:
   cancel: "Cancel"
   create: "Create"
   destroy: "Remove"
   list: "List"
   new: "New"
   update: "Update"
copyright: "© 2012 All Rights Reserved."

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.

Keys-Variants

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, the text “Back button label” will be captured as a file instruction for the string ‘Back’.

YAML

# Back button label
button: '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.

If no wildcards, then the path identifies a single node and all its children (“exact subpath”).
If wildcards, then a path identifies a set of nodes and all their children (“path pattern”). Currently, only the * (asterisk) wildcard is implemented, which means “one or more nodes with any names”.
Exact subpaths have precedence over path patterns.
For example, in the following path specifications:

YAML

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

Smartling processes these paths as follows:

  • /description/text — matches */text.
  • /description/general/text - matches */text directly.
  • /description/text/general — matches its parent, /description/text , matches */text.
  • /system/log/text — matches both /system/log/text (exact path) and */text (pattern). Exact path takes precedence.
  • /system/log/text/details — matches its parent, /system/log/text and system/log/text/details (exact). Exact path takes precedence.

Plurals

Smartling supports two different but incompatible plural translations formats.

Ruby on Rails i18n

When the original language strings use the Ruby on Rails i18n API’s pluralization syntax use the plurals_detection directive to turn detection on. These strings use a parent-child design to indicate the plurals forms. For example:

thingsyouhave:
other: You have %{count} things.
one: You have %{count} thing.

 

ICU MessageFormat

To parse the strings using ICU MessageFormat you can use two Smartling directives string_format with a value of icu

or the  string_format_paths with a value of icu and then specifying array of the specific keys or paths. Smartling paths support simple wildcards. See ICU MessageFormat for additional information.

ICU MessageFormat parsing implies both placeholders and support for advanced formatting syntax such as select statements and plurals. When parsing strings as ICU MessageFormat that default placeholder syntax takes precedence and will always apply if the syntax is present.

 

Standard Placeholder Format

See Placeholders in Resource Files for more on placeholders.

Directives

Format

# smartling.[directive_name] = [value]

 

entity_escaping

Exact delivery depends on file type.

Values auto (default)
true (or yes)
false (or no)
Description Can control whether or not characters will be "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.
Examples

To use inline:
<!-- smartling.entity_escaping = false -->

String:
<!-- smartling.entity_escaping = auto -->

For example, your translation might look like this:
Smartling HTML escaping < > & " example string4

By default, using the "auto" setting, we would assume this is HTML from the <hr> tag and it would be converted to:
Smartling HTML escaping &lt; &gt; &amp; &quot; example string4

Using smartling.entity_escaping = false would allow Smartling HTML escaping < > & " example string4 to appear as it should.

placeholder_format

Values  NONE; C; IOS; PYTHON; JAVA; YAML; QT, RESX 
Description  Used to specify a standard placeholder format.
Examples 

# smartling.placeholder_format = IOS

Specifies iOS-style placeholders for the file.

 

placeholder_format_custom

Values  1) Custom Perl 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. 
Examples 

# smartling.placeholder_format_custom = [.+?]

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

 

plurals_detection

Values  on OR off 
Description  Enables or disables plurals detection. 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.
By default no strings are captured as plural (to avoid false positives).
Add this directive anywhere in your file to turn it on. For precision integration to avoid false positives add a Smartling "on" directive immediately before the plural group and an "off" directive immediately after.
Examples 

# smartling.plurals_detection = on

Smartling will detect plurals in strings below this directive.

 

download_format

Values  NONE(default) OR ESCAPE_UNICODE 
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. 
Examples 

# smartling.download_format = ESCAPE_UNICODE

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

 

string_format

Values  ICU or NONE
Description 

Used only for ICU formatting of strings.  This directive is the easiest/simplest way to specify that all the strings in your YAML file should be parsed as ICU MessageFormat strings.

 

 

 

string_format_paths 

Values 

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

Description 

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
  • ICU - string value will be parsed as ICU MessageFormat
  • @default - (note the leading at-sign) string value will be treated as simple text.

You may specify a single path for a format or a comma-separated array ([]) of paths.

Examples 
# 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 = icu: [*]

Smartling parses all strings as ICU MessageFormat

----

# smartling.string_format_paths =

Disables the effect of the previous string_format_paths instruction.

 

 

pseudo_inflation

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. 
Examples 

# smartling.pseudo_inflation = 80

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

 

yaml_locale_substitution

Values

possible values = full|on|yes|true|off|no|false

Description 

Controls wether or not Smartling will treat the first key in your document as a "language code" that should be replaced with different codes for each target language when you download the translated version of the file.

See Ruby on Rails Localization for more information on this behavior. If you don’t want this to happen, set this directive to false.

default behavior = on/yes/true

 

Examples 

# smartling.yaml_locale_substitution = false

off/no/false 

Prevents Smartling from substituting the first key in translated YAML files. Do not change the value of the first key even if it is a standard language code. E.G. en -> en

on/yes/true (default)

Substitute the first key if it's a standard language code
en: -> es:

Also will use four letter codes if the source file has four letter codes.
en-US: -> es-ES:

full

Substitute the first key if it's a standard language code with the Smartling four letter locale code, even if the source is written as two letter code

en: -> es-ES:

 

pseudo_inflation

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. 
Examples 

# smartling.pseudo_inflation = 80

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

 

sltrans

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. 
Examples

# 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.

Was this article helpful?