Translating Content

CSV Files

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

CSV is a delimited plain text file that uses a comma to separate value. It is supported by almost all spreadsheets and database management programs, including Apple Numbers, LibreOffice Calc, and Apache OpenOffice Calc.

Preparing CSV Files for Translation

It is important that the CSV is encoded in Unicode (or UTF-8) to preserve any special characters in your content. Most programs are encoded as Unicode or UTF-8 by default but the most common spreadsheet program, Microsoft Excel, has some restrictions. To create a CSV from Excel, simply save-as CSV UTF-8 from the file format dropdown.



Directives are commands embedded in code that essentially direct Smartling to the various elements in your file. Examples include which column is your content for translation, where to find translator instructions, where any key or variants are, and command multi-lingual output so all translations are on one file. See examples of these directives below.

When applying directives to files, it's always best to use a text editor to ensure the directives are written in plain text (without formatting). Examples of text editors include SublimeText, TextEdit, TextWrangler, and Notepad++.

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 (column A), 2 (column B) etc.

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.

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. 

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

For download options and how to open a CSV in Excel, see Translated CSV Files.



# smartling.[directive_name] = [value] or [path]

Here are some examples of [directive_name]


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]+}



See Placeholders in Resource Files for more on placeholders.



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 if the translated file should include all translations in one file, a locale per column. 

# smartling.translations_in_columns=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  true / TRUE or false / FALSE (default) 
Description  Defines if the first row in the file is a header, and should be excluded from translation. 
Examples  # 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.

 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




Values  column number - eg: 1

Applies a character limit to the translation which will be visible on the string details in the dashboard and the CAT Tool. The character limit column should be placed somewhere before the translatable column. 

The directive should point to the column that contains a character limit for the string.

The character limit applies only to the first translatable column that placed after the character limit field. You can apply a character limit for each string by inserting a character limit number alongside each string cell.

Examples  # smartling.character_limit_paths = 1


Translating CSV Files

Ensure to create a Files Project for file translation management.

Once you're ready to translate the file, create a Job. All content in the file will be ingested for translation.

By default, no Visual Context will be displayed to Translator from within the CAT Tool. If you would like to provide Translators with Visual Context, upload an image of the content's message. 

If you haven't provided string instructions from within the file using the directive above, you can also provide instructions from the dashboard to provide context.

By attaching a JPG or PDF document for reference, the Translators can download the attachment in the CAT Tool.

If you haven't applied character limits to the content from within the file using the directives above, applying character limits to strings in the dashboard can help done to ensure translations are kept to a certain length. 

When translations are complete, download the published translations to your locale drive.

Translated CSV Files

If you are using a program that is encoded with Unicode (or UTF-8) by default, then proceed to open the file as you would normally. In most cases, Microsoft Excel will be your default program for spreadsheet files. A simple double-click on your downloaded CSV could open your translated file in Excel with multiple corrupt characters. This is because Excel is not encoded with Unicode by default.

To open your CSV file safely in Excel, follow these steps;

1) Download translations from Smartling

2) Open a new blank workbook in Excel (separately)

3) In Excel, go to the Data tab, click From Text. Choose the translated CSV file from your local drive and click Get Data



Depending on your version of Excel, there is a series of steps to follow in a pop-up like this​​.

4) Ensure Delimited is selected

5) In the File Origin dropdown, scroll down and choose Unicode (UFT-8) > Next

6) Ensure the Delimiters are set to Comma > Next​​


7) Ensure the Column data format is Text > Finish

​Choose where you want the data > OK


Was this article helpful?