Extension .csv
Smartling identifier csv
Resources Comma-Separated Values (CSV) files RFC

String Instructions

Set using string_instructions_paths directive.

Specifying Paths

Some directives require you to specify a path or set of paths to keys or strings in the file. A path in CSV files is simply a column number, such as 1

Note: When declaring a path for a key or string instruction the key or instruction will be applied to the next translatable string to the right, so you will need to organize your files so that keys and instructions are to the left of translatable strings in each row.

Other Information

You may define values with and without quotations. For example:

value1, "Value 2"

If you want to use the symbol " inside quoted value you escape it with double quotes like:


which corresponds to the string: value"178"

Smartling offers several options for downloading CSV files. More info


Directive Format

# smartling.[directive_name] = [value]

Directives are specified using comments. Each directive must be a single comment on one line, and there should not be any inline trailing symbols after the directive. The directives must be defined at the top of the file, ahead of the csv content.


Values:String of characters (default is ,
Description:Defines the sequence of characters that separate values in a record line.
# smartling.field_separator=,

Fields are separated with a , character


Values:String of characters (default is ")
Description:Defines the sequence of characters that may enclose values. To use the character sequence inside values you should escape it with repeating twice (default is "").
# smartling.string_encloser="

String literals are inclosed in " characters


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 columns as HTML.



Values of all columns to be ingested as strings.

For import, all values will be imported for the selected locale.


Defines the column numbers with values to be ingested as translatable strings.

For multilingual translations import it defines association column number with target import locale.


For uploading original file:

Comma-separated list of column numbers.

For multi-language imports:

Comma-separated list of column/locale pairs:

# smartling.paths=2,3

Specifies that columns 2 and 3 of the uploaded CSV file should be ingested as translatable strings.

# smartling.paths=2/es-ES,3/fr-FR

When importing translations, specifies that column 2 contains Spanish-SPAIN translations and column 3 contains French-FRANCE translations.


Values:Column Number - eg 4

Used for "download multiple languages by row" option. Defines a column to record the language for each row. Output will display a language code for each column, eg. "de", "en", "es", etc.

This column should exist in the original file as an empty column.

Note: if using this directive, you should also use smartling.paths to exclude the language path column from translation. See example below.

# smartling.translation_language_path = 4

When the translated file is downloaded, column 4 will record the language for each row.


Values:true | TRUE or false | FALSE(default)
Description:Defines if the original source strings should be included when downloading multiple languages.
# smartling.output_original_row=TRUE



A comma separated list of paths to use create "keys" for strings on translate_paths.

The key will be a space separated string of all the keys leading to the source string. For example: "string", "group1 string".


Used to define the schema for capturing a key for each source string. Keys are required:

  • If you want to import pre-existing translations from a file with the same structure
  • If you want to create variants of strings that would otherwise be duplicates (By default Smartling does not create duplicate strings.)

    Note: creating or updating variants for previously uploaded strings cause new strings to be created that will not have translations. The SmartMatch feature can be configured to automatically apply the existing translations, or translators can use the 100% match from the Translation to manually apply the translation.

  • Specify the full path to the value, then indicate which part of the path should be used as the key using {} notation.

# smartling.source_key_paths = 1

Smartling will capture data from column 1 as keys. Each key will be applied to the next translatable string after it, so keys need to be placed to the left of translatable strings in each row for this directive to work


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


Values:true | TRUE or false | FALSE(default)
Description:Defines whether all Smartling directives in the source file should be removed from translated files when downloaded.
# smartling.strip_instructions_on_download=TRUE


Values:true | TRUE or false | FALSE(default)
Description:If TRUE, the first non-empty string in a CSV file will be treated as a header and excluded from translation.
# smartling.first_row_header=TRUE


Values:Comma-separated list of columns.

Specifies which columns contain string instructions. This directive must be used together with smartling.paths to specify translatable strings.

Each string instruction is applied to the next translatable string, so you must place your instruction column to the left of the translatable string. You may have more than one instruction column per translatable string.

# smartling.paths=4
# smartling.source_key_paths=1
# smartling.string_instructions_paths=2,3
# smartling.first_row_header=true

Smartling will capture the content in the files as follows. Column 1 will be captured as key metadata, Columns 2 and 3 will be string instructions. Column 4 contains the translatable strings


Values:Alternative labels for smartling locales in JSON format

Defines how languages are labeled in downloaded CSV files. Default label is the Smartling locale code, such as "fr-FR", but you may wish to choose a different label, such as "French" in order to make the file easier to read or to match the labels used in your application.

# smartling.locales_map={“es-ES”:”Spanish”,”de-DE”:”German”}

Downloaded translations will be labeled as "Spanish" for es-ES and "German" for de-DE.


Values:true | TRUE or false | FALSE(default)

Determines whether to force addition of a UTF-8 Byte Order Mark (BOM) to the output file when downloading translations.

If set to FALSE (default), output files will only include a BOM if the original file did.

If set to TRUE, a UTF-8 BOM will be added to the output file, even if none existed in the original file.

Note: This applies to UTF-8 only. For UTF-16, BOM is always used.

# smartling.add_utf8_bom=TRUE


Values:true | TRUE(default) or false | FALSE

Determines if rows with no translations for a given locale are included in output files.

If output_not_translated_row=TRUE (default), a row with no translations will still be included in the output file, even if there are no translations for that locale.

If set to FALSE, rows with no translations will be excluded from the output file.

# smartling.output_not_translated_row=FALSE

If this file has four rows, and only rows 1-3 have translations for French, the downloaded file for fr-FR will exclude row 4.


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.