Preparing Content for Translation


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


String Instructions

Set using string_instructions_paths directive.

You cannot set both string_instructions_paths and string_format_paths for HTML at the same time; if you want do use HTML parsing you will need to add instructions to strings via the Smartling dashboard.


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.

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:


"She said ""hello"" to me."

This corresponds to the string: She said "hello" to me

Smartling offers several options for CSV Download Options.

Standard Placeholder Format

See Placeholders in Resource Files for more on placeholders.



# smartling.[directive_name] = [value]



Description Used to specify a standard placeholder format.

# smartling.placeholder_format = IOS

Specifies iOS-style placeholders for the file.



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.

# smartling.placeholder_format_custom = REGEX

Any characters surrounded by square brackets will be treated as a placeholder. For example:
# smartling.placeholder_format_custom = {[0-9]+}




Values integer - Accepted values are 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.






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.

Overrides string_instructions_paths.


# smartling.string_format_paths=html:*

Smartling parses values of all columns as HTML.




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 by repeating twice (default is ""). 



# smartling.string_encloser="

String literals are inclosed in " characters




Values  Values of all columns to be captured as strings. 
Description  Defines the column numbers with values to be captured as translatable strings. For multilingual translations import it defines a column and locale.


For uploading original file:
Comma-separated list of column numbers. # smartling.paths=1,2

For multi-language imports:
Comma-separated list of column/locale pairs # smartling.paths=1/[LocaleID],2/[LocaleID]


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




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

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.




Values  Column Number - for example: 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.

If using this directive, you should also use smartling.paths to exclude the language path column from translation.



# 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  If TRUE, the first non-empty string in a CSV file will be treated as a header and excluded from translation. 
Examples  # smartling.first_row_header=TRUE 



Values  Alternative labels for Smartling locales in JSON format. 
Description  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 the 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.

Examples  # smartling.add_utf8_bom=TRUE 



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



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. 
Examples  # smartling.strip_instructions_on_download=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.

 Ignored if string_format_paths is set to HTML.

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.

# smartling.string_instructions_paths=2

Was this article helpful?