The Cloudwords CLI (command line interface) allows developers to easily create Cloudwords projects and get content translated. It is also designed to be scriptable and can be integrated with your SCM (source control management) system or your continuous integration process. This tutorial will illustrate just how simple it is to get your source content into Cloudwords and retrieve the translations once delivered by the vendor.
We welcome your feedback on the CLI. If you have questions, suggestions, or need support using the CLI, please contact us at support@cloudwords.com.
For this tutorial, you will need:
1. A Cloudwords sandbox account. Don't have one? Create one now.
2. The API Access Key for your account. Learn how to get it here.
3. Java 8 or higher
4. The CLI Distributable makes it super simple to integrate with Cloudwords from the command line.
It is recommended you place the CLI executable (cw-cli) somewhere in your PATH. Suggested installation instructions are provided below.
$ cd /opt $ sudo tar -xzf cw-cli-version.tar.gz
Add the following line to the end of your ~/.bashrc file.
export PATH=/opt/cloudwords-cli:$PATH
Before you start using the CLI, you'll need to log in with your API key.
$ cw-cli login prod api-key
The Cloudwords CLI stores your credentials and project details in $HOME/.cloudwords/
Running cw-cli without arguments will print a list of "tools". A tool is invoked by running cw-cli tool. A tool
will print usage information with a command in the pattern cw-cli tool --help.
Before creating projects, it generally helps to set default values for properties like the Department and Source Language. Projects cannot be created without a Department, but source language is optional. Note: If info --department lists no departments, or only a single department, then you do not need to set a default department.
$ cw-cli info --department Available Departments: ID Department Name 1 Unassigned 99 Product 101 Development 263 Customer Success 513 Channel 515 Legal 611 Sales 955 Marketing $ cw-cli defaults --department 955 Defaults updated Default Project: Not set Default Department for new projects: Marketing (#955) Default source language for new projects: Not set Default target language(s) from new projects: Not set Root directory: None
A simple command will create a project.
$ cw-cli project --create "test project" Successfully created project 15315
To add a source file use the push tool
$ cw-cli push test.txt Uploading /Users/cloudwords/test.txt Uploaded 1 files
Note: Creating a project (or updating one) sets that project to the default project. This default can be controlled with the defaults tool. Operations which do not specify a project ID execute on the default project. See the usage information for each tool to see how to specify the project ID.
For convenience, the project create and push commands can be combined into a single command.
$ cw-cli project --create "test project" test.txt Successfully created project 15316 Uploading /Users/cloudwords/test.txt Uploaded 1 files
Additionally, the parameter --updated can be added to the above command. This will suppress upload of a file, if that file has not been changed since it was last sent out for translation, or if it is currently in translation in an active project. No project will be created at all unless at least one file is eligible for upload.
In order to download translations, it is necessary to set the project pattern. This pattern allows the CLI to determine where a translated file should be saved, based on the location of the source. A simple pattern would be %D/%l/%N. This would store the translation in a sub-directory of the directory the source file was in named with the target language code. The target file would have the same name as the source file. For instance, if this pattern were applied to the project created in the previous example, and the target language were French, the target location would be /Users/cloudwords/fr/test.txt.
| Code | Definition |
|---|---|
| %D | The absolute path of the directory that contains the source file (e.g. /Users/cloudwords) |
| %d | The name of the directory that contains the source file (e.g. cloudwords) |
| %N | The full name of the source file (e.g. test.txt) |
| %n | The name of the source file, without the extension (e.g. test). This includes the name up to the last dot in the filename |
| %E | The extension of the filename, including the dot (e.g. .txt) |
| %e | The extension of the filename, without the dot (e.g. txt) |
| %L | The full name of the target language (e.g. French or French (France)) |
| %l | The target language code (e.g. fr or fr-fr) |
The pattern may be set at any time before translations are downloaded using the project tool. The following command will update the pattern for the default project.
$ cw-cli project --pattern %D/%l/%N
This option can also be added when creating a project to set the pattern when the project is created.
The pull tool (cw-cli pull) will download translations. The -x parameter (--cross-project) will pull translations for all projects. The -a parameter (--approved) will only
pull translations that have been approved. The Cloudwords API provides the last time a translation was updated, once a translation has been pulled it will not be downloaded again until it is updated.
The Cloudwords CLI is intended to be scriptable. This means that it can be used in shell scripts to automate your translation process in various ways. A prime example of this is to automatically submit files for translation when updates to them are committed to your version control repository (git, Mercurial, Subversion, etc.).
The following script is an example of a post-receive hook for git. It will automatically create a project when files ending in -en.html in the root are updated. The script should be easy to modify to handle whatever source files you are targeting. The script requires an existing working directory, which it will update in order to check source files and perform commits.
#! /bin/bash
# To use this script, name it hooks/post-receive in your central git repository.
# Set the parameters below based on the details of your installation
REPO=/Users/cloudwords/version-control-test/gitrepo
WORKING_DIR=/Users/cloudwords/version-control-test/working/git
CW_CLI=/opt/cloudwords-cli/cw-cli
unset GIT_DIR
cd $WORKING_DIR
git pull
# pull -x means "pull for all projects", -a means "only pull files which have been reviewed and approved"
$CW_CLI pull -x -a
CHANGES=$(git status -s | wc -l)
if [ "$CHANGES" != "0" ]; then
git add --all .
git commit -m "(Cloudwords Integration) Add translations from Cloudwords"
git push
fi
HEAD=`git rev-list --count HEAD`
# This is the project name
PROJECT_NAME="Changes in $HEAD"
# The files to translate are set at the end of the last command
$CW_CLI project -c "$PROJECT_NAME" --pattern %D/%n-%l.html -u *-en.html
#!/bin/sh
# To use this script, name it hooks/post-commit in your central svn repository.
# Set the parameters below based on the details of your installation
CW_CLI=/opt/cloudwords-cli/cw-cli
WORKING_DIR=/Users/cloudwords/version-control-test/working/svnrepo
if [ ! -e "$WORKING_DIR" ]; then
svn co "file://$1" $WORKING_DIR
else
cd $WORKING_DIR
svn update
fi
cd $WORKING_DIR
$CW_CLI pull -x -a
CHANGES=$(svn st | wc -l)
if [ "$CHANGES" != "0" ]; then
svn add --force * --auto-props --parents --depth infinity -q
svn ci -m "(Cloudwords Integration) Add translations from Cloudwords" --force-log
fi
$CW_CLI project -c "changes in $2" --pattern %D/%n-%l.%e -u *-en.html
This script should be easy to modify for your particular source control system. However, since it only runs when a commit is made, this may result in delays in receiving translations. To improve this, the following script can be run as a cron job.
#! /bin/bash
# Set the parameters below based on the details of your installation
REPO=/Users/cloudwords/version-control-test/gitrepo
WORKING_DIR=/Users/cloudwords/version-control-test/working/git
CW_CLI=/opt/cloudwords-cli/cw-cli
unset GIT_DIR
if [ ! -e "$WORKING_DIR" ]; then
git clone $REPO $WORKING_DIR
else
cd $WORKING_DIR
git pull
fi
cd $WORKING_DIR
$CW_CLI pull -x -a
CHANGES=$(git status -s | wc -l)
if [ "$CHANGES" != "0" ]; then
git add --all .
git commit -m "(Cloudwords Integration) Add translations from Cloudwords"
git push
fi
#! /bin/bash
CW_CLI=/opt/cloudwords-cli/cw-cli
WORKING_DIR=/Users/cloudwords/version-control-test/working/svnrepo
if [ ! -e "$WORKING_DIR" ]; then
svn co "file://$1" $WORKING_DIR
else
cd $WORKING_DIR
svn update
fi
cd $WORKING_DIR
$CW_CLI pull -x -a
CHANGES=$(svn st | wc -l)
if [ "$CHANGES" != "0" ]; then
svn add --force * --auto-props --parents --depth infinity -q
svn ci -m "(Cloudwords Integration) Add translations from Cloudwords" --force-log
fi
By adding the last line of the of the post-receive script to the script above, it can also create projects. This may be useful if you cannot create a post-receive hook in your control system. This is the case for many cloud-based version control services.