# WebTranslateIt Synchronization Tool : wti [RubyDoc](http://rubydoc.info/github/AtelierConvivialite/webtranslateit/) | [Report a bug](http://github.com/AtelierConvivialite/webtranslateit/issues) | [Support](https://webtranslateit.com/support) | [WebTranslateIt.com Homepage](https://webtranslateit.com) wti lets you easily sync your language files with [WebTranslateIt.com](https://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... * 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... * include a rack middleware you can use in your Rails app to automatically fetch new translations from WebTranslateIt.com. * include libraries you can use to programmatically fetch your segments from WebTranslateIt.com. See [Extras](https://github.com/AtelierConvivialite/webtranslateit/wiki/Extras) * include a web interface for your translation team to update your language files. [Learn more on the web_translate_it_server project page](https://github.com/AtelierConvivialite/web_translate_it_server). --- ## Installation You will also need ruby to run `wti`. On Linux or a Mac, it’s already installed. Install [RubyInstaller](http://rubyinstaller.org/) if you’re using Windows. [See detailed installation instructions for Windows users](https://github.com/AtelierConvivialite/webtranslateit/wiki/Install-wti-on-Windows). ``` bash $ gem install web_translate_it Fetching: web_translate_it-2.1.3.gem (100%) Successfully installed web_translate_it-2.1.3 1 gem installed ``` At this point you should have the `wti` executable working: ``` bash $ wti -v wti version 2.2.1 ``` On some Linux distributions you may get the following error: ``` bash $ wti If 'wti' is not a typo you can use command-not-found to lookup the package that contains it, like this: cnf wti ``` The reason is that the wti file is named in another way: `/usr/bin/wti.ruby2.1` so you will have to create a symlink to make wti run. ``` bash # ln -s /usr/bin/wti.ruby2.1 /usr/bin/wti ``` ## Configuration Now that the tool 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. ``` bash $ 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. ## Usage Execute `wti --help` to see the usage: Usage: wti [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 --help` for more information on a specific command. [options] are: --config, -c : 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= ISO code of locale(s) to push -t, --target Upload all target files -f, --force Force push (bypass conditional requests to WTI) -o, --low-priority WTI will process this file with a low priority -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= Apply a label to the changes -c, --config= 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 statistics
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`](https://github.com/AtelierConvivialite/webtranslateit/blob/master/examples/.wti#L9..L13) file for implementation. ## Exit codes Since version 1.4.0 `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. ``` zsh ~/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 ``` Since version 2.4.1 the `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. ``` zsh ~/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 (c) 2009-2019 WebTranslateIt Software S.L, released under the MIT License.