crowdin-maven-plugin

A command line tool to handle synchronization of the source code with translations made on Crowdin.

Maven plugin for crowdin (http://crowdin.net/)

Requirements:

Git is installed and configured properly.
Have a valid Crowdin Project ID and its key.
Maven is installed

Configuration:

Add the Following properties in the maven settings.xml (contact with admin of crowdin exo-platform-35 project to get project key and id):

<exo.crowdin.project.id>{projectId}</exo.crowdin.project.id> <exo.crowdin.project.key>{projectKey}</exo.crowdin.project.key>

Download:

Get the latest version of the code:

git clone https://github.com/exoplatform/crowdin-maven-plugin.git

This will create a folder and copy the necessary files into it.

Usage:

Build master branch with : mvn clean install Switch to translation branch. Open a terminal in the translation branch, and run the following commands:

1. Initialization

mvn clean install -Pinit

This will execute the plugin with the goal 'init':

-- load the properties of each project

-- browse them to identify master files and translations

-- create folders on Crowdin if they don't exist

-- upload the master files and translations of each master file on Crowdin if they don't exist

Note: If there are nonexistent master files in file system, there will be a warning like

There are nonexistent properties files! Check again and update properties configuration files or run following command to continue: mvn clean install -Pinit -Dforce=true

2. Synchronization

mvn clean install -Psync

This will execute the plugin with the goal 'sync':

-- load the properties of each project

-- browse them to identify master files and translations

-- create new folders, upload new master files and translations (new entries in the properties of each project)

-- update master files content on Crowdin (add new keys, rename existing keys, delete keys)

-- delete old folders and files (old entries in the properties of each project and not exist in file system)

Note: If there are nonexistent master files in file system, there will be a warning like

There are nonexistent properties files! Check again and update properties configuration files or run following command to continue: mvn clean install -Psync -Dforce=true

Warning: All Crowdin files corresponding to nonexistent properties files will be deleted after execute above command

We can rely on above message to know if there are some master files renamed in source code. In this case, we need update manually these master files by content and translations from Crowdin before do a synchronization again with -Dforce=true

3. Updating

mvn [clean] install -Pupdate [-Dlangs=<all | en,fr,it,...>] [-Dapply_approved_only=<true|false>]

This will execute the plugin with the goal 'update':

-- export and download all translations

-- create "Crowdin" branches in source code if they were not existing or update them with latest changes from stable branch

-- inject the translations of the specified languages into the code. The languages are defined via the 'langs' parameter.

Note: We need commit manually "Crowdin" branches and push them to github repository

4. Upload Translation

mvn clean install -Pupload-translation

This is used to update changes in projects' translation files to Crowdin. It uses the information provided in the properties files (upload-translation.properties and .properties files) under upload-translation folder to determine the projects and their translation files need to be updated (in the same convention as the plugin's crowdin.properties and .properties files)

Steps:

Identify the list of projects need to be changed, put them into upload-translation.properties. Each entry is a key/value pair with key = - and value = <path to project's description file>
For each project create the project description file named .properties. In this file provide the path to the project in the 'baseDir' property and list all the translation files need to be updated in the form of =
Run 'mvn clean install -Pupload-translation'

5. Restore translation

mvn clean install -Prestore-translation [-Dprepare=true | -Dcontinue=true] [-Daction=createProject]

This restores a Crowdin project's directory structure and translations from its zip file. This zip file should be built with 'Export Only Approved' and 'Don't Export Untranslated' options unchecked so it will backup the untranslated and all suggested translations (not only the approved ones) as they will need to be restored also. Since this zip contains the project's directory structure and all of its translations, it can be considered as a project's backup and should be rebuilt (with 'Build Fresh Package' under Crowdin's 'Downloads' tab) and kept safe before doing any activity that may mess up the project.

This can also be used to clone a Crowdin project from its zip file (by changing the project's API key to point to another project).

Steps:

Rename the project's zip file as 'all.zip' and put it under the plugin's crowdin-zip folder
If the master files do not exist (e.g in case you want to do a clone, or you had deleted them all using Crowdin's 'File Manager' to rebuild from scratch - this is recommended), you must first re-create the project's structure with '-Daction=createProject' option, the plugin will extract the zip and walk through its directories and files to create the same structure on Crowdin.
When having the master files ready, run 'mvn clean install -Prestore-translation', the plugin will (by default) upload translations of every languages it finds in the zip.

If you want to decide what to be uploaded to Crowdin, you can: first run with 'Dprepare=true' option to get the plugin stops after preparing the extracted folder for you to modify, e.g to remove some languages or projects you don't want to upload. When you're done, let the plugin continues by running with '-Dcontinue=true' option, it will upload your modified folder instead of the original zip.

6. Command line options

-- dryRun If true, no communication with Crowdin will be done; Default: false. Useful to see the evolution of the process. Combined with maven debug option -X, displays actual Rest calls and XmlPath queries.

Contributing:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request