Shell Scripts

As an easy way to access Smartling’s API functionality, Smartling offers a package of BASH scripts, which can be used to Upload, Download and Delete files in a Smartling project from the command line. The scripts are hosted in Smartling's GitHub repository.

The package contains five executable scripts, used for accessing the API, and two resource scripts, which contain configurations used by the executable scripts.

Executable Scripts:

upload.sh - Uploads files to a smartling project.
download.sh
- Downloads translated files from a Smartling project.
delete.sh - Deletes resource files from a Smartling project.
download-glossary.sh - Downloads a project’s glossary.
download-tmx.sh - Downloads a project’s translation memory.

Resource Scripts:

settings.sh - Contains information needed to access Smartling’s API.
common.sh - Contains common code used by other scripts.
globals.sh - Contains common code used by other scripts.

Before using the bash scripts, modify settings.sh with the Project ID and API Key for the project you want to interact with. Project ID and API key are available from the dashboard at Project Settings > API .

To use API scripts to upload, download or delete a file:

The commands to upload, download or delete a file, follow this format:

[action] [options] [directory OR file]

Action : The name of the desired executable script - ‘upload.sh’, ‘download.sh’, or ‘delete.sh’

Options : Set each options parameter for the script. Options can either pass extra information to a script, such as a list of locales, or act as a flag to turn on a particular behaviour, such as downloading only completed files.

For example, to use the ‘download.sh’ script to download files including pending translations, and creating subfolders based on file URI, enter ‘-t pending -S’.

Each script has different options parameters. Refer to the detailed instructions for each script, below.

Directory or File: The target directory (for a download) or the path to the local file (for an upload).

For example: to download the translated files for French and German, using the pending translations and save them in the directory ‘translations’, use:

./download.sh -t pending -l "fr-FR de-DE" translations

Upload

This script uploads a resource file to Smartling. You must specify the type of file. All other parameters are optional. You can specify multiple files to upload, separated by a space, but all files must be of the same type. You may also use wildcards. For more information on parameters, see the API documentation.

Example commands:

./upload.sh -t json strings.json
Uploads the file strings.json to Smartling.

./upload.sh -t json -u prefix -x legal strings.json strings2.json
Uploads the files strings.json and strings2.json to Smartling with the prefix ‘/legal/’.

./upload.sh -t json *.json
Uploads all files from the current directory that have a .json extension.

Parameter Flag Required/Optional Description/Values
File Type -t Required

Smartling’s unique identifier type of file you are uploading. Note that this may not be the same as the file extension. For example, an XLIFF file may have the extension ‘.xml’, but you must specify the file type ‘xliff’. See our Files Integration for the unique identifier for each file type.

Accepted values: android, ios, gettext, plaintext, csv, html, xml, json, javaProperties, yaml, qt, xliff, docx, pptx, xlsx, idml, resx

Example:

./upload.sh -t json strings.json
File URI scheme -u Optional Determines how Smartling will allocate a URI to the uploaded file. If unspecified, default is ‘fileName’Accepted values are:fileName - the URI will be the name of the filerelativePath - the URI will include relative folder information in addition to the file nameprefix - The URI will be the name of the file with a specified prefix. (see the Prefix parameter)
Prefix -x Optional Adds a prefix to a file’s URI in Smartling. To use this function, you must also set the File URI scheme to ‘prefix’.Example:./upload.sh -t json -u prefix -x legal strings.jsonThis command will upload the file strings.json. In Smartling, the file will have the URI ‘/legal/strings.json’
Callback -c Optional Sets a callback URL for a GET request to be sent when all strings in a file are published for a locale. The GET request will have the parameters 'fileUri' and 'locale'.Example:./upload.sh -t json -c http://requestb.in/xxmpg1xc strings.json
Test mode -e Optional If this flag is set, the upload will run in test mode. The script will return a list of files that would have been uploaded, but will not actually upload any files.
Placeholder format -p Optional Regular expression to define custom placeholders. See documentation for the file type you are uploading.

Download

This script downloads either original or translated versions of a file from Smartling. The file will be saved in the specified directory. If you download translations, then additional locale subfolders will be created. You must specify a Download Type. All other parameters are optional. For more information on parameters, see the API documentation.

Example commands:

./download.sh -t pending -l “fr-FR de-DE” -O -W translations

Download files with pending translations for French (France) and German (Germany) locales to the folder ‘translations’. Where there is no translation, download the original string. Downloaded files overwrite existing files.

./download.sh -t published -C translations

Download only completed files for all available project locales with published translations to the folder ‘translations’

Parameter Flag Required/Optional Description/Values
Download Type -t pending - Any translation that exists for a string will be downloaded.published - Only completed translations are downloadedpseudo - Downloads the original string with extra characters to allow you to test the effect of longer strings in your UI.original - Downloads the original files contextMatchingInstrumented - Downloads a modified version of the original file with strings wrapped in a specific set of Unicode symbols - used to improve context matching with the Chrome Context Capture Extension.Example:./download.sh -t published translations
URI mask -u Optional Filters files to be downloaded. For example, entering the value ‘strings’ will download only files with a URI containing the text ‘strings’. Find the URI of your files by checking the file names at Files>Resource Files
Locale -l Optional List of locales to include in the download. For example “es-ES ja-JP” downloads Spanish (Spain) and Japanese (Japan). By default, all available locales are downloaded. Note that you can only specify locales that are in use for the project.
Completed files only -C Optional Only files with all translations completed will be downloaded
Append locales to file names -A Optional Appends the locale to each file name, instead of creating separate folders for each locale.
Create subfolders -S Optional Saves the downloaded files in subfolders based on the file URI.
Include Original Strings -O Optional Downloads translated files with the original strings where no translation is available. By default, strings with no translation will be blank in translated files. Valid for gettext, custom xml, and json files only.
Overwrite -W Optional Downloaded files will overwrite existing files with the same name.

Delete

This script deletes resource files from a Smartling project. For more information on parameters, see the API documentation.When you run a delete script, you will see a list of files to be deleted and prompted to enter ‘YES’ to continue with the deletion.

Example commands:

./delete.sh -u strings.json

Deletes all files where the URI contains the text ‘strings.json’ from Smartling.

Parameter Flag Required/Optional Description/Values
URI Mask -u Required Filters files to be deleted. For example, entering the value ‘strings’ will delete only files with a URI containing the text ‘strings’. Find the URI of your files by checking the file names at Files>Resource FilesExample:./delete.sh -u strings.json

To download glossary:

Note: This process assumes you have already edited your settings.sh file to specify your API Key and Project UID.

1) From the command line, use the ‘cd’ command to navigate to the directory where you have saved your scripts.

2) Use this command template to download your glossary:

./download-glossary.sh [options] [directory]

Directory: Specify a directory path to save the glossary files.

Options:

Parameter flag Required/Optional Values/Description
Download Type -t Optional

Type of file to download. Specify ‘CSV’ or ‘TBX’. Default value is ‘CSV’

Example:

./download-glossary.sh -t TBX glossary/
Locale -l Optional List of locales to include in the download. For example “es-ES ja-JP” downloads Spanish (Spain) and Japanese (Japan). By default, all available locales are downloaded. Note that you can only specify localesthat are in use for the project.

Example:

./download-glossary.sh -t CSV -l “fr-FR” glossary/project/

Download glossary in CSV format for French (France) to the directory ‘glossary/project’.

To download translation memory:

Note: This process assumes you have already edited your settings.sh file to specify your API Key and Project UID.

1) From the command line, use the ‘cd’ command to navigate to the directory where you have saved your scripts.

2) Use this command template to download your translation memory:

./download-tmx.sh [options] [directory]

Directory: Specify a directory path to save the translation memory files.

Options:

Parameter Flag Required/Optional Values/Description
Download Type -t Optional

Type of file to download:

full(default) downloads all translations.

published downloads only published translations

Example:

./download-tmx.sh -t published translation_memory/
Locale -l Optional List of locales to include in the download. For example “es-ES ja-JP” downloads Spanish (Spain) and Japanese (Japan). By default, all available locales are downloaded. Note that you can only specify localesthat are in use for the project.

Example:

./download-tmx.sh -t full -l “fr-FR” translation_memory

Download Translation Memory in full for French (France) to the directory ‘translation_memory’