Supported File Types

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.

Content Parsing

Default

If you upload a YAML file without any custom Smartling directives, Smartling will:

    1. Capture all values in the file as strings.
    2. Use the complete name path to each string as key and variant data.
    3. Create placeholders in the strings using a default regular express to capture a number of common placeholder formats.
    4. Not capture any string instructions
    5. Deliver translations, one file per language.

HTML

If a string contains HTML, Smartling automatically parses the strings in the file with basic HTML parsing, even without any HTML directive. Just note, this basic parsing will not break down the YAML value with HTML into smaller strings. It is ingested as one string. If this is not desirable and you want the value to be broken down into smaller strings in Smartling based on the HTML formatting, you can use the string_format_paths HTML feature. This will benefit both your translation resources and your translation memory leverage.

It is worth noting that in doing so, you lose any "keys", however, you still have "variants". In most cases, such as translation Jobs, this is acceptable, however, this is not acceptable if you are importing translations from a file, as keys are critical for alignment.

Example YAML value:

terms: "<p>These are the terms you should be aware of them.</p><h1>First things first</h1><p>The first thing about the terms is that they apply to you.</p><h1>Second things second</h1><p>The second things about the terms is that they apply to us.</p>"

 

Regular Parsing

(1 string with key + variant)

HTML parsing

(5 strings with variant only - translations cannot be imported)

<p>These are the terms you should be aware of them.</p><h1>First things first</h1><p>The first thing about the terms is that they apply to you.</p><h1>Second things second</h1><p>The second things about the terms is that they apply to us.</p>
  1. These are the terms you should be aware of.
  2. First things first
  3. The first thing about the terms is that they apply to you.
  4. Second things second
  5. The second things about the terms is that they apply to us.

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 (either inline or via API):

  1. string_format with a value of icu
  2. 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.

If ICU string formatting is used, then that takes precedence over HTML and any HTML directive will be ignored if your directives resolve in a value being parsed for both ICU and HTML. It is possible in a single file to have both HTML formatted strings and ICU formatted strings, but they must be on different paths.

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.

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'

Keys-Variants

By default, every string is created with variant metadata. The variant metadata is the full path of keys leading to the translatable string.

Custom key paths can be set, and variant behavior turned off with directives.

Placeholder Format

Default

If you do not specify a custom placeholder format, even if you specify other directives, Smartling will convert the following subtext of a string into a placeholder for that string:

  • {x}
  • {{x}}
  • ${x}
  • %x%
  • %%x%%
  • ##x##
  • __x__

Custom

If you want to control how Smartling will capture the content and metadata from your YAML file, or specify a custom placeholder format, you can use custom Smartling directives. The directives can be added "inline" to the file or they be configured as API parameters.

YAML inline directives must be the "first" or "top" object in the JSON
If you are integrating "inline" the the integration "smartling" must be the first object in the JSON.

The syntax for directives might change if you are using them as API parameters instead of inlining them.

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 Java 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 = REGEX

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

 

plurals_detection

Values  on|yes|true or off|no|false
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.

 

yaml_strict_plurals_detection

Values  on|yes|true or off|no|false (default)
Description 

Enables or disables strict 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.

This directive comes in conjunction with the above directive smartling.plurals_detection = on, so the file should include both
If this directive is enabled - Yaml plural detection rules become more strict and if there is another plural form than in original language - plural detection is cancelled for the current Yaml node. 

Examples 

# smartling.yaml_strict_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
  • Markdown - string value will be parsed as Markdown.
  • @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.

Wildcards are allowed in path definitions.

  • If no wildcards are used, then the path identifies a single node and all its children ("exact subpath").
  • If wildcards are used, then a path identifies a set of nodes and all their children ("path pattern"). Currently, only * (asterisk) wildcard is implemented, which means "one or more nodes with any names".
  • Exact subpaths have precedence over path patterns.

See Content Parsing for more information.

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.

Considerations

When to use multiple string_format_paths in a single document, recommended use case:

If your document has disparate kinds of strings that are used in different contexts, for example, if your single YAML file contains application UI strings, with standard string formatting and placeholders, together with one or few keys that are just giant HTML documents (example; TOS or Privacy Policy).
Just remember the side effects of HTML parsing, including losing keys, and precendence rules for other formats.

 

 

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:

 

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?