Preparing Content for Translation

YAML

 

Extension .yaml
Smartling Identifier yaml
Example File (see below for example)
Resources Rails Internationalization

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

YAML file example:

---
no: "No"
yes: "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 plural translations when the original language strings use the Ruby on Rails i18n API’s pluralization syntax. To avoid mistakenly capturing strings as plurals because they happen to use the key name one, other, etc., use the plurals_detection directive to turn detection off.

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.
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_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
@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.

Examples 

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.

# smartling.string_format_paths = html: *

 

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 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 on Rails Localization for more information on this behavior. If you don’t want this to happen, set this directive to false. 
Examples 

# smartling.yaml_locale_substitution = false

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

 

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?