Translation Memory

Importing Translated Resource Files

There are two ways to import translations in Smartling - TMX upload of an existing Translation Memory, and importing a translated resource file of translations completed outside Smartling that want to add to your Smartling Translation Memory.

This article covers the latter - importing a translated resource file, such as this example CSV (continue reading to learn more about the keys and directives used.)

Skip ahead to watch our video tutorial on how to import translated spreadsheets.

Permitted Users and Supported File Types

Account Owner and Project Manager users can import translations for the following file types via the Files page:

* CSV files do not generate keys automatically and directives are required.

HTML processing and file imports are not compatible.

If your translations are in a Microsoft Office Document, the translations must be aligned to the source content. You can copy and paste the content to an Excel file and convert that into a CSV to proceed with file prep by making up a key for each string. Ensure each string has its own cell, in the same column.


This translation import is referred to as key-based import as it is based on a 1:1 mapping of an original language resource file and its translated version, using keys. A key is a unique identifier for a string.

Most of the supported file types listed above are fixed file formats that generate keys for each string automatically. Unlike most, CSV files require manual creation of keys for each string. A key can contain letters, numbers, and some special characters (such as hyphens or underscores). 

Example File 1: Source


Example File 2: Translations


The import file must contain a unique key for each string.

As the source language is required for any translation import, using a unique key for each string aligns the translations at a string-level. This means that the source language maps to the target language per string, as seen above.

Ensure your translated file is parsed correctly before importing to ensure the translations are truly aligned.

For CSV imports, it is important to align keys and strings per column, as shown above. Your file should have a column for keys, a column for the source language, and if you are importing source and translations in one file, a column for each translated language. Alignment on a row-level is not supported. 


File directives are used to define the location of specific data in a file. Directives are found at the beginning of the file, before the content.

Download an example source file here.

CSV requires the use of directives with any upload to Smartling. Other supported file types listed above do not necessary require directives, depending on how you want to import the translation. If you want to simply upload a separate file for each language, including the source, directives are not required (excluding CSV).

Importing one file with multiple languages

Importing one file with multiple languages will require the addition of file directives to ensure that Smartling can read where the keys are located in the file, and where the content you are importing is located in the file. 

This method is also error-prone, and can easily corrupt your Translation Memory. Consult your Customer Success Manager or Solutions Architect for advice on importing one file with multiple languages. 

File Preparation Checklist

  1. The first step in importing translations is to ensure that the content in the source file is parsed correctly.
    • This article gives details on how each file type is parsed.
  2. Use keys to identify each string and map the source string to the correct translation. 
    • Keys must be unique for each string
  3. Ensure the translations are in fact translations.
    • Check that your translated file does not contain a different language, such as the source language, if a translation for a string is missing. If the translated file does not have a translation for every source string, you should omit it for the purpose of importing to Smartling. Depending on your file format, you may include the key but leave it blank/“empty”/null/“” or omit the key/value entirely.
  4. Use source file type directives to ensure that the file is parsed correctly so that Smartling ingests the file accordingly.

Important Notes

The translations are saved to the Translation Memory as soon as the upload has been completed, regardless of the workflow step chosen.

If you happen to accidentally import translations for the wrong language (i.e., the directive in the file points to a different target language than the one you just imported the file to), it is imperative that you go to the Translation Memory that the project is writing to, find the strings that were imported inaccurately, and delete the terms before proceeding to reimport.

How to Import Translations

  1. Go to the project that is writing to the Translation Memory that you want to import the translations to.
  2. Click the Files tab
  3. Upload the file in the source language first. 
  4. Next, if your translations are in the same file as the source, change the # smartling.path directive to point to the target language you are about to upload next
    • In the example translated CSV file, the # smartling.path will point to the second column for the source upload (# smartling.path=2), and then the third column when uploading French (# smartling.path=3)
  5. Once the source content is upload, enter the file by clicking the tile.
    • The target languages of the project will be listed under the source language.
  6. On the target language, you want to import translations to, click the ellipsis button (beside the Download button)
  7. Select Import Translations
  8. Upload the translated file. 
  9. Choose the workflow step at which you want the translations: First Revision Step or Published.
    • If you want the imported translations to be reviewed and approved by reviewers on your Smartling account before being published, choose the First Revision Step. If you're confident that the translation is of good quality, click Published. In either case, the translations are immediately saved to the Translation Memory as soon as the import is complete (step 11). The content is imported into the language’s default workflow. If your default language workflow has no post-translation steps, you should choose Published.Screenshot_2020-11-16_at_14.15.54.png
  10. To overwrite existing translations in Smartling with the translation import, select the Overwrite existing translations checkbox.
  11. Click ImportScreenshot_2020-11-16_at_14.15.15.png
  12. A success message will display the total number of matched strings and list any import errors. An issue will be automatically created for each string with an import error.
  13. Click Start another upload to upload more translations in the same language. Click Close to close the dialog and commence importing translations for another language by repeating from step 5.


If there is an error message, it may be the result of one or more of the following:

  • Placeholder mismatch
  • Inconsistent file directives
  • Different key/value pairs

The most common import error is placeholder mismatch. This may be caused by having different placeholder directives in the original and translated files. If a later import has no errors, these issues will be resolved automatically.

Another possible cause of a placeholder mismatch error is if the number of placeholders in the source is different from the number of placeholders in the target. If this error is flagged, the strings will still be imported but they will automatically be the first step in the language workflow, regardless if you chose published on step 8 above.

To rectify this:

  • Ensure the number of placeholders in the source equal the number of placeholder in the target
  • Ensure the placeholders are formatted correctly
  • Ensure the placeholder directives are correct

Once these errors are resolved, you can re-import the translated file using the steps above.

Assuming that each source string has a translation, the total number of strings, matched strings, and imported strings should be equal. If the number of matched strings is 0, this could mean there is a misalignment of keys, or the file directives are not pointing to the correct translations. If translations are not matched, then they are not imported.

To rectify this:

  • Ensure to check the strings keys and file directives before uploading
  • Ensure each string has a unique key
  • Ensure the keys are aligned to the translations

For more information, see Upload a Translation Memory (.TMX) File and Find and Replace Translations, and Translation Memory Management

HTML Processing

HTML processing and file imports are not compatible. Directing Smartling to HTML process the strings in a file can break the string into smaller components, and therefore they cannot be assigned a key, and a translation cannot be imported.

If you have a key-based resource file with previously translated strings that you would also like to have HTML processed, you must first upload the file without HTML processing, import the translations, then re-upload the source file with HTML processing turned on. Smartling will create new and different strings, and may be able to use SmartMatch to apply translations to them, but some strings may need to be completely re-translated within Smartling.

HTML processing of strings is recommended only if your individual strings contain large blocks of content that are formatted with HTML that are not well translated as individual strings. Contact Smartling if you are not sure the best way to handle your resource files.


Importing content is also available via API.

Video tutorial: Importing translations from a spreadsheet


Step 1: Choose the correct file format 00:45
◦ Add keys as string identifiers
◦ Save your spreadsheet as a CSV (comma-separated values) file
◦ Prepare your source file with file directives
  1st directive: first_row_header
  2nd directive: source_key_paths
  3rd directive: smartling.paths
  Additional directives (optional)
◦ Save your CSV file with the directives

Step 2: Upload your source file to Smartling 07:44

Step 3: Import the translations 08:11
◦ Amend the smartling.paths directive
◦ Save your CSV file with the updated directives
◦ Import the translations to Smartling

Help & Support 12:00

Was this article helpful?