CSV or comma-separated values is a commonly used text file format, which is used to store table data. Many platforms and applications support the export and import of content in a CSV format.
Microsoft Excel files or Google Sheets can also be easily converted into a CSV format.
CSV files are often a more suitable alternative, as they provide more control and flexibility.
Generally speaking, we would recommend opting for a CSV format (instead of Microsoft Excel or Google Sheets) if your file contains:
- String identifiers like keys or variants, which should be uploaded to Smartling as searchable metadata,
- Placeholders for variable text elements, or
- HTML tags.
These elements cannot be processed correctly in Excel.
CSV files, on the other hand, allow you to handle all of these elements in a fully customizable way, by applying instructions called file directives. File directives are inline instructions that can be added to your CSV file to tell Smartling exactly how your file should be processed.
In this tutorial, we will walk you through the process of preparing your CSV file with directives, to ensure that all of its elements will be uploaded correctly to Smartling.
Step 1: Converting spreadsheets to a CSV format
If you would like to upload a spreadsheet (from Microsoft Excel or Google Sheets) in a CSV format, please follow this tutorial to convert the file to the correct format.
Info: If you are downloading a CSV file from Excel or Google Sheets, please note that any colors or styling will not be preserved. As CSV is a purely data-based format, any styling is not retained in the translated output file.
Step 2: Adding file directives
Tip: Please ensure to use a text editor, such as Sublime Text, when adding directives to your CSV file (as shown in the below video tutorial).
When directives are added directly in Microsoft Excel or Google Sheets before the file is converted to a CSV format, this may lead to invisible columns (and therefore commas) being added to the directives, rendering them ineffective.
Info: Below, you will find video tutorials on how to add some commonly used directives. Of course, you can add more or less directives, as required for your exact CSV file.
A full list of all available CSV file directives is available here.
First row is a header: Specify if the first row should stay untranslated
If the first row in your file only contains headers that should remain untranslated, apply the following directive:
# smartling.first_row_header=TRUE
Source content: Specify which column(s) should be translated
This video shows how to apply Smartling's paths directive to specify which column(s) contain(s) the source content to translate.
Info: If your file contains any rows that should not be uploaded for translation, they need to be excluded manually. Aside from the first row, which can be marked as untranslatable with the “First Row is a Header” directive, rows cannot be excluded with a CSV directive.
If your files regularly contain multiple rows to be excluded, Microsoft Excel may be a suitable alternative, as it allows you to mark up not just an entire column, but also single rows and cells as untranslatable, with the NOTRANSLATE cell style.
[Optional] String keys: Specify which column contains string identifiers
If your file contains string keys, follow this tutorial to apply Smartling's source key paths directive.
Info: Once this directive is applied, keys are uploaded to Smartling as string metadata, and can be searched for in the Strings View.
By default, keys are also used as string variants in Smartling.
[Optional] Specify a placeholder format
If your source content contains placeholders, apply a file directive to use either a standard placeholder format or a custom placeholder format.
Tip: To learn more about supported placeholder formats and to get more examples, visit our documentation on Placeholders in Resource Files.
[Optional] Translations in columns: Download all languages in one file
By default, you will receive one translated output file per language. To download all languages in a single file, opt either for Translations in Columns or Translations in Rows.
Tip: In step 5 of this tutorial, we will show you how to download all translations in a single file.
[Optional] Additional file directives
Of course, additional directives can be applied as required for your file. You can find a full list of all available CSV file directives here.
For example, you can indicate a column containing translator instructions or character limits, or specify that the strings in your file should be parsed as HTML or markdown.
Tip: HTML tags in a CSV file are automatically recognized and blocked from translation. No additional directive is required to parse tags correctly.
Step 3: Save the file with the directives
Once all required directives have been added, please save the file with UTF-8 encoding.
Step 4: Creating a translation Job
Once the file has been prepared and saved, follow this tutorial to upload it for translation.
Info: By default, no visual context is available when translating CSV files. If you would like to provide some visual context for the translators, you will need to use an alternative solution, for example by providing images as visual context, or by using Smartling’s Context Capture Chrome extension to upload context from a website.
Step 5: Downloading the translated file
This short video shows how to download and open the translated CSV file.
Tip: If you would like to download the translations for all languages in a single file, please ensure to apply the relevant file directive to either retrieve Translations in Columns or Translations in Rows.
File templates: Use a pre-configured set of directives
To reduce the effort of adding directives to your CSV files, Smartling offers the option to set up pre-configured file templates that allow you to drag and drop your files without any manual preparation work.
Please feel free to reach out to your Smartling Customer Success Manager if your CSV files always follow the same format and the same set of file directives should be used across all of them.
Tip: To have a pre-configured template created for your files, please indicate the name(s) of the project(s) that it should be used for, as well as all directives that should be included.
Once the template has been created, you can drag and drop CSV files without any manual preparation:
- Simply follow the usual process to create a translation Job.
- A drop-down menu with all available templates will appear automatically when you are uploading a new CSV file.
- Select the correct template, and then continue to create and authorize the translation Job.
- All directives included in the template are applied automatically to the file upon upload.
Duplicate strings
Learn how duplicate strings with identical source text are processed upon upload to Smartling.
Troubleshooting: Using an alternative character as a field separator
Typically, CSV (comma-separated values) files use the comma (,) as a field separator.
If, however, the comma is used in your region as a decimal separator, a different symbol - usually a semicolon (;) - may be used as a field separator. If this is the case for your region, an additional directive needs to be added to avoid parsing issues in Smartling.