README

Introduction:
Zanata Python client is a client that communicates with a Zanata server
[http://zanata.org/] to push text for translation (from publican documents or
gettext-based software), and pull translated text back for inclusion in 
software or documentation builds.

It also provides support for creating projects/versions in Zanata and retrieving
information about projects.

Install:
You can install the zanata-python-client with 'yum install zanata-python-client' 

To install from source:
   make install

Compiling:

make lint: runs pylint against the source code.

make test: runs unit tests.  Note: To run the unit tests, you will also need minimock: 'yum install python-minimock'

Configuration:
After you install the zanata-python-client, you need to create a global configuration file $HOME/.config/zanata.ini that contain user-specific configuration. 
For creation of zanata.ini can be found on http://zanata.org/help/cli/cli-configuration/

For each project, you also have to write a project-specific configuration file named zanata.xml.
Sample zanata.xml file can be found on https://github.com/zanata/zanata-server/blob/master/zanata.xml

You can also override the URL of the server with the command line option '--url'. 
There are also command line options '--username' for user name and '--apikey' for api key of user. 

Command List:

Name: /usr/bin/zanata

Type "zanata" in the shell, it will give you basic information of command
for working with Zanata server. You can use "zanata --help" to get more
information about the commands of zanata.

Basic Usage: zanata COMMAND [ARGS] [COMMAND_OPTIONS]

Listing / Querying for Projects

$ zanata list

Creating a project

$ zanata project create {project_id} --project-name={project_name} --project-desc={project_description}

Create a Project Version

$ zanata version create {version_id} --project-id={project_id} --version-name={version_name} --version-desc={version_description}

Query for information of a project

$ zanata project info --project-id={project_id} 

Query for information of a project iteration

$ zanata version info --project-id={project_id} --project-version={version_id} 

Publishing Templates (source text) to Zanata

If you want to push only one template file to zanata server, you can use command below:

$ zanata publican push --project-id={project_id} --project-version={iteration_id} [documentName..]

If documentName is omitted, 'publican push' command will push all the
template files under the template folder to Zanata server. You can
specify the path of template folder by command line option '--srcdir'. If
you don't provide such info, the command will try to locate template folder
in current path.

$ zanata publican push --project-id={project_id} --project-version={iteration_id} --srcdir={template_folder}

$ zanata publican push --project-id={project_id} --project-version={iteration_id} 

Or you can simply run below command in a folder contain template folder with zanata.xml, command will load all the info from configuration file:

$ zanata publican push 

You can enable 'import-po' option, then related translation (po files) will be pushed to zanata server at the same
time.
You need to specify the parent folder that contain all the translation by 'transDir' command line option. By default, command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to push to the zanata server by 'lang' option

$ zanata publican push --import-po --trandir={path of parent folder contains locale folders} --lang=lang1,lang2,..

By default, the server will try to find closest equivalent translation from oter versions in the same project and copy to version you specified. You can set no-copytrans to disable that function

$ zanata publican push --no-copytrans

Retrieving translated Documents from zanata

If you want to retrieve only one file from zanata server, you can use command below:

$ zanata publican pull --project-id={project_id} --project-version={iteration_id} [documentName..]

Without indicate the documentName, this command will pull all the documents of a project version on zanata server to a local output folder. Command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to pull from the zanata server by 'lang' option

$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder} 

$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,..

you can also simply running below command in a folder contain zanata.xml, command will load all the info from configuration file:

$ zanata publican pull

Push and pull software project with Zanata

If you want to push only software project file to zanata server, you can use command below:

$ zanata po push --project-id={project_id} --project-version={iteration_id} [documentName..]

Without indicate the documentName, 'po push' command will push all source file of software under the po folder to zanata server. You can specify the path of po folder by command line option, if you don't provide such info, the command will try to locate po folder in current path

$ zanata po push --project-id={project_id} --project-version={iteration_id} --srcdir={po_folder}

$ zanata po push --project-id={project_id} --project-version={iteration_id} 

Or you can simply running below command in a folder contain po folder with zanata.xml, command will load all the info from configuration file:

$ zanata po push 

You can enable 'import-po' option, then related translation will be pushed to zanata server at the same time. you can specify the parent folder that contain all the translation by 'transdir' command line option, or the client will use the path of po folder as the 'transdir'.  By default, command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to push to the zanata server by 'lang' option

$ zanata po push --import-po --trandir={path of parent folder contains translation files, such as zh-CN.po} --lang=lang1,lang2,..

By default the server will try to find closest equivalent translation from oter versions in the same project and copy to version you specified. you can set --no-copytrans option to disable that function.

$ zanata po push --no-copytrans

Retrieving Software project translation from zanata

If you want to retrieve software translation from zanata server, you can use command below:

$ zanata po pull --project-id={project_id} --project-version={iteration_id} [softwareName..]

Without indicate the software name, this command will pull all the translations of a project version on zanata server to a local output folder. Command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to pull from the zanata server by 'lang' option

$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder} 

$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,..

you can also simply running below command in a folder contain zanata.xml, command will load all the info from configuration file:

$ zanata po pull