webtranslateit

A CLI to sync locale files with webtranslateit.com.

117
34
Ruby

WebTranslateIt Synchronization Tool : wti

Gem Downloads |
Report a bug |
Support |
WebTranslateIt.com Homepage |
Docker Package

wti lets you easily sync your language files with WebTranslateIt.com, a web-based tool to translation software.

WebTranslateIt Synchronization Tool

wti…

  • wti is a command-line tool. It works on all operating systems: Windows, Linux, MacOS X, … It is also available as a Docker package.
  • wti is really easy to use. It was inspired by git. Use wti push and wti pull to sync your language files with WebTranslateIt.com.

Optionally, wti does…


Installation

You will also need ruby to run wti. We require ruby version 3.0 or newer. On Linux or a Mac, it’s already installed. Install RubyInstaller if you’re using Windows. See detailed installation instructions for Windows users.

$ gem install web_translate_it
Fetching: web_translate_it-3.0.2.gem (100%)
Successfully installed web_translate_it-3.0.2
1 gem installed

At this point you should have the wti executable working:

$ wti -v
wti version 3.0.2

We also provide wti as a Docker packages. See our packages and instructions to install.

Configuration

Now that wti is installed, you’ll have to configure your project. Basically, wti is to be run on a project root directory, and looks for a .wti file containing your project information. The command wti init lets your create your .wti file.

$ wti init proj_pvt_V8skdjsdDDA4
# Initializing project

 The project Frontend was successfully initialized.

You can now use `wti` to push and pull your language files.
Check `wti --help` for help.

proj_pvt_V8skdjsdDDA4 is the API token, which you can find in your project settings.

If you’d like to specify another path for your configuration file, you can use wti init. This command will ask you to enter your project API token and where to save the configuration file (by default it will create a .wti in your project root directory).

Now you’re all set and you can use the wti commands on your project.

Using on multiple projects

Please refer to our documentation about syncing multiple projects.

Usage

Execute wti --help to see the usage:

Usage: wti <command> [options]+

The most commonly used wti commands are:

  pull        Pull target language file(s)
  push        Push master language file(s)
  match       Display matching of local files with File Manager
  add         Create and push a new master language file
  addlocale   Add a new locale to the project
  server      Start a synchronisation server
  status      Fetch and display project statistics
  init        Configure your project to sync      

See `wti <command> --help` for more information on a specific command.

[options] are:
  --config, -c <s>:   Path to a translation.yml file (default: .wti)
     --version, -v:   Print version and exit
        --help, -h:   Show this message

Append --help for each command for more information. For instance:

$ wti push --help
wti push [filename] - Push master language file(s)
[options] are:
  -l, --locale=<s>        ISO code of locale(s) to push
  -t, --target            Upload all target files
  -f, --force             Force push (bypass conditional requests to WTI)
  -m, --merge             Force WTI to merge this file
  -i, --ignore-missing    Force WTI to not obsolete missing strings
  -n, --minor             Minor Changes. When pushing a master file, prevents
                          target translations to be flagged as `to_verify`.
  -a, --label=<s>         Apply a label to the changes
  -c, --config=<s>        Path to a configuration file (default: .wti)
  --all                   DEPRECATED -- See `wti push --target` instead
  -d, --debug             Display debug information
  -h, --help              Show this message

Sample Commands

Command Action
wti add path/to/master/file.po Upload a new master language file
wti add file1.po file2.po file3.xml Create several master language files at once, by specifying each file
wti add *.po Create several master language files at once, by specifying an extension
find . -name "*en.yml" | xargs wti add Find all the en.yml files and add them to the project
wti push Update a master language file
wti push -l fr Update a target (French) language file
wti push -l "fr en da sv" Update several target language files at once (French, English, Danish, Swedish)
wti push --all Update all language files at once
wti push path/to/file.yml Pushes the path/to/file.yml file
wti pull Download target language files
wti pull -l fr Download a specific language file (French)
wti pull --all Download all language files, including source
wti pull path/to/files/* Download all files in path/to/files
wti pull path/to/files/* -l fr Download all fr files in path/to/files
wti pull --force Force pull (to bypass WebTranslateIt’s HTTP caching)
wti addlocale fr Add a new locale to the project
wti addlocale fr da sv Add several locales at once
wti status View project translation statistics
wti status config/locales/app/en.yml View translation statistics on file config/locales/app/en.yml
wti match Show matching between files on local computer and the ones in WebTranslateIt’s File Manager

Hooks

It is sometimes useful to hook a command or a script before or after a push or a pull. One use-case would be to launch a build after pulling language files. You can do that by implementing hooks in your .wti file.

There are 4 hooks:

  • before_pull
  • after_pull
  • before_push
  • after_push

Check the sample .wti file for implementation.

Exit codes

wti returns exit codes on failure. The exit code is 0 if the command executed successfully and 1 if the command executed but encountered at least one error. This is useful to act upon errors if you use wti to pull files in an automated build process.

~/code/webtranslateit.com[master]% wti pull
# Pulling files on WebTranslateIt
 config/locales/translation_validator/en.yml        | e82e044..e82e044  Skipped
 config/locales/app/en.yml                          | f2ca86c..f2ca86c  Skipped
 config/locales/defaults/en.yml                     | 2fcb61f..2fcb61f  Skipped
 config/locales/js/en.yml                           | ee6589d..ee6589d  Skipped
 config/locales/js/fr.yml                           | 2f8bb0e..2f8bb0e  Skipped
 config/locales/translation_validator/fr.yml        | 534af2c..534af2c  Skipped
 config/locales/app/fr.yml                          | 29f8c9d..da39a3e  OK
 config/locales/defaults/fr.yml                     | aca123e..aca123e  Skipped
Pulled 8 files at 7 files/sec, using 3 threads.

~/code/webtranslateit.com[master]% echo $?
0

~/code/webtranslateit.com[master]% wti pull
# Pulling files on WebTranslateIt
 config/locales/translation_validator/en.yml        | e82e044..e82e044  Error
 config/locales/app/en.yml                          | f2ca86c..f2ca86c  Skipped
 config/locales/defaults/fr.yml                     | aca123e..aca123e  Skipped
Pulled 3 files at 3 files/sec, using 3 threads.

~/code/webtranslateit.com[master]% echo $?
1

wti status command also returns meaningful codes. It will exit with 0 if the project is 100% translated and proofread, 100 if the project is not 100% translated and 101 if the project is not 100% proofread. This could allow you to check if a project is 100% translated or completed before deploying a project.

~/Desktop/test% wti status
# Gathering information on test ts
fr: 40% translated, 40% completed.
en: 90% translated, 0% completed.

~/Desktop/test% echo $?
100

~/Desktop/test% wti status
# Gathering information on test ts
en: 100% translated, 0% completed.
fr: 100% translated, 100% completed.

~/Desktop/test% echo $?
101

~/Desktop/test% wti status
# Gathering information on test ts
en: 100% translated, 100% completed.
fr: 100% translated, 100% completed.

~/Desktop/test% echo $?   
0

License

Copyright © 2009-2024 WebTranslateIt Software S.L, released under the MIT License.