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 ensure 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.
Default Parsing
If you upload a YAML file without any custom Smartling directives, Smartling will:
- Capture all values in the file as strings.
- Use the complete name path to each string as key and variant data.
- Create placeholders in the strings using a regular expression to capture a number of common placeholder formats.
- Captures file comments as string instructions
- Deliver translations, one file per language.
HTML Parsing
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>"
Default Parsing |
HTML Parsing |
1 string with key + variant |
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> |
|
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):
string_format
with a value oficu
string_format_paths
with a value oficu
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
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 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.
XML Characters
The following XML character are always escaped. You can control this by using the entity_escaping directive.
Character (character name) | Escape sequence |
< (less-than) |
< |
> (greater-than) |
> |
& (ampersand) |
& |
' (apostrophe or single quote) |
' |
" (double-quote) |
" |
Directives
File directives are supported, both inline and via our API. Directives are specified in comments within the files, in the following format:
Inline File Format
# smartling.[directive_name] = [value]
API Parameter
smartling.[directive_name] = [value]
Here are examples of supported directives for YAML:
Directive name | Values | Description | Example |
download_format |
|
Controls Unicode character escaping on file download. ESCAPE_UNICODE indicates that all non-Latin1 (not in range 0000 - 00FF of Unicode) symbols after this command should be escaped by \uXXXX |
# smartling.download_format = ESCAPE_UNICODE
Smartling will escape the
|
entity_escaping |
(case-insensitive) |
Controls whether base characters ( > < & " ) are "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. |
For example, your translation might look like this: By default, using the "auto" setting, we will assume this is HTML from the <hr> tag. When the translated file is downloaded, the translated string will be escaped as: Using #smartling.entity_escaping = false will allow is above string to appear unescaped. |
entity_escaping_type |
(case-insensitive) |
By default, all html4 entities are unescaped, except the basic set: < > & ". When this directive is set to html5, all html5 entities will be unescaped as well. |
# smartling.entity_escaping_type = html5 |
entity_escaping_strategy |
(case-insensitive) |
Used to retain entity escaping for all non-base entities. For example, normally we turn © into © but if we use this new directive the translation will automatically update to use escaping from the source. For each entity character, we'll check to see if it was escaped in the source and try to match (propagate) it in the target. If HTML5 entities are required as well, you must use the entity_escaping_type=propagate directive.
|
# smartling.entity_escaping_strategy = propagate If the same character is both escaped and unescaped in the same string, propagate will return the characters in the translation escaped in the same order as they were in the source. However, if there are a different number of characters in the translation where the translation process removed or added some and the escaping is inconsistent among them, propagate will escape all entities for that character. This does not affect source content at all - so using it will not result in new strings. propagate will only affect non-base entities - all named entities except & , ", <, >. Base entities continue to be controlled by HTML detection and the entity_escaping directive. Numerical entities are not considered at all with this directive, and are treated normally. |
placeholder_format |
|
Used to specify a standard placeholder format. |
# smartling.placeholder_format = IOS Specifies iOS-style placeholders for the file. |
placeholder_format_custom |
|
Specifies a custom placeholder format. Any text in your file matching the regular expression you provide will be captured as a placeholder. See Placeholders in Resource Files for more on placeholders. |
# smartling.placeholder_format_custom=\{([^}]+)\} Any characters surrounded by curly brackets, e.g., {first name}, will be treated as a placeholder. |
plurals_detection |
|
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. To avoid false positives, add a Smartling "on" directive immediately before the plural group and an "off" directive immediately after. |
# smartling.plurals_detection = on Smartling will detect plurals in strings below this directive. |
pseudo_inflation |
Integer values between 0 - 100 |
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. |
sltrans |
|
Use this directive to enable or disable processing of translation strings in the file. You must turn translation back on once you're done with notranslate. Any content with this tag will not appear in the Smartling dashboard, but will appear in your translated file in your original source language.
|
# 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. |
string_format_paths |
The value of this directive is expressed as [format]:[paths]. Current supported formats are:
|
Specifies the format of strings for the specified paths and can enable HTML inside another file format. Separate multiple paths 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. Wildcards are allowed in path definitions.
See Content Parsing for more information. |
# smartling.string_format_paths = Disables the effect of the previous string_format_paths instruction. # smartling.string_format_paths = html: /product/description Enables HTML in /product/description only. # smartling.string_format_paths = html: /product/description/ Enables HTML in /product/description and all its child nodes. # smartling.string_format_paths = html: /product/description/, html: /product/title Enables HTML in /product/description and all its child nodes, and the product/title node. # smartling.string_format_paths = block: /product/description Enables block and everything inside of root to be one string.
|
whitespace_trim |
|
A whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character is not a visible mark, but does occupy an area or space on a page. Although whitespaces are necessary within a string (typically to separate words), unnecessary whitespaces can be found at the start of a string (leading) and at the end of a string (trailing). With this directive, you can manage whitespace trimming. By default, the leading and trailing whitespaces are trimmed. You can choose to disable trimming or specify trimming for leading or trailing whitespaces. The directive can be used inline or as the API request parameter.
|
# smartling.whitespace_trim=on Smartling will trim leading and trailing whitespaces (default)
# smartling.whitespace_trim=off Smartling will not trim leading or trailing whitespaces
# smartling.whitespace_trim=leading Smartling will trim only leading whitespaces
# smartling.whitespace_trim=trailing Smartling will trim only trailing whitespaces |
yaml_locale_detection |
|
Used to correct source string keys in translation imports when YAML format is ruby localization format and the root node is the language ID. |
# smartling.yaml_locale_detection=true This directive is recommended for successful translation import. |
yaml_locale_substitution |
|
Controls whether 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. |
# smartling.yaml_locale_substitution = false Prevents Smartling from substituting the first key in translated YAML files. Smartling will not change the value of the first key, even if it is a standard language code, e.g.,. en -> en # smartling.yaml_locale_substitution = 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, e.g., en: -> es-ES
|
yaml_strict_plurals_detection |
|
Enables or disables strict plural 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 works with the directive, # smartling.plurals_detection = on, so the file should include both |
#smartling.plurals_detection = on #smartling.yaml_strict_plurals_detection = on Smartling will detect plurals in strings below this directive.
|