diff --git a/docs/commands/init.md b/docs/commands/init.md new file mode 100644 index 00000000..3cdabd95 --- /dev/null +++ b/docs/commands/init.md @@ -0,0 +1,47 @@ +# Command: init + +To initialise a project from the command line, the `init` command can be used. This command will guide you through the steps necessary to set up a new or existing project, and start using Zanata. + +These instructions assume that you have installed zanata-cli version 3.4.0 or higher as shown in [Installing the Client](installation). + + + +## Getting started + +The first thing to do is to type the following command in the console: `zanata-cli init` + +The client will proceed to ask which of your preferred Zanata servers it needs to use to register your new project (this information is taken from your `zanata.ini` file; if the desired server does not appear in the list, it should be added to this file). + +```bash +[INFO] Loading project config from zanata.xml +[INFO] Loading user config from /home/camunoz/.config/zanata.ini + Found servers in zanata.ini: + 1) http://localhost:8080/zanata/ + 2) https://translate.jboss.org/ + 3) https://translate.zanata.org/zanata/ +[?] Which Zanata server do you want to use? +``` + +Select the Zanata server to use by typing in the number and hiting ENTER. The client will now ask whether you want to create a new project, or use an existing one from your instance: + +```bash +[?] Do you want to 1) select an existing project or 2) create a new one (1/2)? +``` + +According to your selection the client will ask for information about your new project and proceed to create it, or it will give you an option to select an existing one from the server. + +```bash +[?] What project ID/slug do you want to have (must start and end with a letter or number, and contain only letters, numbers, underscores and hyphens): +$ my-project-id +[?] What project name do you want to have: +$ My Project Name +[?] What is your project type ([utf8properties, properties, gettext, podir, xliff, xml, file])? +$ podir +[>] Project created. Now it's time to create a version to host your files. + +[?] What version ID/slug do you want to have: +$ master +[>] Version created. +``` + +the Zanata client will continue to ask questions and provide information on the next steps necessary to get you started with your project on Zanata. \ No newline at end of file diff --git a/docs/commands/pull.md b/docs/commands/pull.md new file mode 100644 index 00000000..b47451c4 --- /dev/null +++ b/docs/commands/pull.md @@ -0,0 +1,43 @@ +# Command: pull + +To download documents from your project-version, the command-line client's `pull` command can be used. + +These instructions assume that you have installed zanata-cli as shown in [Installing the Client](installation), and have saved user and project configuration as shown in [Configuring the Client][configuration]. + + +## Translation Document Download + +The basic command for downloading documents is `zanata-cli pull`. The pull command should always be run from the directory that contains `zanata.xml` for your project (find information about `zanata.xml` at [Configuring the Client][configuration]). + +At the time of writing, you will have to specify source and translation directories with the command, even though the default pull command will pull only translated documents from the server. This will be fixed in a future version. This means that the simplest pull command is: + +```bash +zanata-cli pull -s src -t trans +``` + + +This command will: + + 1. look up the locales to pull from `zanata.xml` (all the enabled locales by default). + 1. display the current settings and list of locales that will be downloaded. + 1. confirm that you want to proceed with the download. + 1. download translated versions of any documents that have any translations. + +Documents with no translations will not be downloaded unless specifically requested by adding the `--create-skeletons` option. + +To download only a few locales, use the `-l` or `--locales` option. For example, to download only Japanese and Russian translations, I might run `zanata-cli pull -s src -t trans -l ja,ru`. You can also modify the locales in `zanata.xml` if you will be consistently specifying a different set of locales. + +For a full list of the available options for pull, run `zanata-cli help pull` + + +## Source Document Download + +The pull command can also download source documents. This is generally only for reference purposes since source documents cannot be changed on the server. + +To pull translations instead of source documents, add the option `--pull-type source`, like so: + +``` +zanata-cli pull --pull-type source -s src -t source +``` + +To pull source and translation documents together, use `--pull-type both`. diff --git a/docs/commands/push.md b/docs/commands/push.md new file mode 100644 index 00000000..f04c7743 --- /dev/null +++ b/docs/commands/push.md @@ -0,0 +1,62 @@ +# Command: push + +To upload documents to your project-version, the command-line client's `push` command can be used. + +These instructions assume that you have installed zanata-cli as shown in [Installing the Client](installation), and have saved user and project configuration as shown in [Configuring the Client][]. + + + +## Source Document Upload + +The basic command for uploading documents is `zanata-cli push`. The push command should always be run from the directory that contains `zanata.xml` for your project (find information about `zanata.xml` at [Configuring the Client][configuration]). + +At the time of writing, you will have to specify source and translation directories with the command, even though the default push command will push only source documents to the server. This will be fixed in a future version. This means that the simplest push command is: + +`zanata-cli push -s src -t trans` + +This command will: + + 1. search for source documents in a directory named `src` and any of its subdirectories. + 1. display the current settings and list of source documents that were found. + 1. confirm that you want to proceed with the upload. + 1. upload the located source documents to the server. + +*Note:* if your source files are in the same directory as non-source files that have the same extension, such as when using Java `.properties` files for both translation and configuration, the `--includes` or `--excludes` option should be used to tell Zanata which files it should push. + +For a full list of the available options for push, run `zanata-cli help push` + + +## Translation Document Upload + +The push command can also upload translations. This is mainly for use when translation has started on your project before it has moved to Zanata. Translators can also use this command to upload translations, although translation on the Zanata website is safer. + +To push translations instead of source documents, add the option `--push-type trans`, like so: + +```bash +zanata-cli push --push-type trans -s src -t trans +``` + +To push source and translation documents together, use `--push-type both`. + +These commands will upload all available translations for the locales specified in `zanata.xml`, unless the `-l` or `--locales` option is used to specify a smaller set of locales. For example: `-l ja,de`. + +*Note:* translation documents must be named appropriately to match a source document. The appropriate name depends on your project type. For example, if the above command is used for a Java Properties project with a source document `src/strings/messages.properties`, a Japanese translation for the document would be at `trans/strings/messages_ja.properties`. + +```bash +src + strings + messages.properties +trans + strings + messages_ja.properties +``` + +If you are unsure about the layout and naming for translation files in the selected project type, you can do a trial pull and look at the output. This can be done by copying `zanata.xml` to an empty folder and running a pull command such as: + +```bash +zanata-cli pull -s src -t trans --create-skeletons +``` + +The option `--create-skeletons` is used to make sure files will be written even if there are no translations. + +For more information on the pull command, see [Document Download with Client](commands/pull). diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..ae69713f --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,122 @@ +# Configuring the Client + +zanata-cli requires User Configuration and Project-Version Configuration. + +## User Configuration + +User configuration stores your credentials so that zanata-cli can prove to the server that requests are from you rather than an imposter. The information in your user config should be kept secret. + +zanata-cli expects to find user configuration in `.config/zanata.ini` within your user directory. + +To add configuration for a Zanata server: + + 1. Use your favourite text editor to create or open `zanata.ini` in `~/.config/`. + 1. Sign into the Zanata server and navigate to the user settings page + 1. Ensure that an API Key is shown. If you do not have an API Key, click 'Generate API Key' now. +![User settings page](images/302-user-settings.png) + + 1. Copy the contents of the text-box labeled 'Configuration [zanata.ini]'. + 1. Paste the copied lines into `zanata.ini` and save the file. + + +## Project-Version Configuration + +Project configuration stores information about a project-version, and should be kept in the project directory. + +zanata-cli expects to find project-version configuration in a file named `zanata.xml` in the project directory. + +To add project-version configuration to your project directory: + + 1. Sign into the Zanata server and navigate to the appropriate version of your project. + 1. Click the `Download config file` link to initiate download of `zanata.xml`. +![Download config file link on version page](images/350-version-config-file.png) + + 1. Save `zanata.xml` in your project directory. + + +These steps should be repeated for each project-version before using any zanata-cli commands for the project-version. + +You can customize `zanata.xml` with command hooks so that other tools will automatically run before or after Zanata commands. Read about command hooks at the [command hook page on the wiki](https://github.com/zanata/zanata-server/wiki/Client-Command-Hooks). + + +## Locale Configuration + +The `zanata.xml` will contain a list of locales so that the client knows which locales to push and pull to/from the Zanata server. When downloaded from the Zanata server, the list will have the locales as specified by the server itself. It will look something like this: + +```xml + + es + ja + fr + zh-Hant-TW + ... + +``` + +Sometimes the way locales are named in your project files doesn't match Zanata's locale nomenclature, so it's necessary to create a mapping between the two. You can achieve this in the client by modifying the locale entries in `zanata.xml`. + +For instance, if one of your files is called `myfile/es.po` and your project in Zanata has the `es-ES` locale, then your client mappng would look like this: + +```xml + es-ES +``` + +### Translation files mapping rules + +You can also customize the way translation files are found when pushing, as well as the location they will be saved to when pulling. +{% highlight xml %} + + + {locale}/{path}/{filename}.po + {path}/{locale_with_underscore}.po + +{% endhighlight %} + +In the example above, `pattern` identifies a source file, and the contents of the `rule` element specify how translation files will be stored. + +The `pattern` attribute is a [glob](http://en.wikipedia.org/wiki/Glob_(programming)) matching pattern to your source document file(s). You can define more than one rule and apply each rule to a specific set of source documents using different patterns. The **first** matched rule will be applied to the file. + +`pattern` is optional. If not specified, the rule will be applied to all source documents in your project. +The actual rule consists of literal path and placeholders/variables. + +Supported placeholders/variables are: + + 1. **{path}** is the path between source document root (what you define as src-dir option) and the final file. + 1. **{filename}** the source document name without leading path and extension. + 1. **{locale}** the locale for the translation file. If you use "map-from" argument in your locale mapping, this will be the map-from value. + 1. **{locale\_with\_underscore}** same as above except all hyphens '-' will be replaced with underscores '_'. This is typically used in properties and gettext projects. + 1. **{extension}** the source document file extension + +For example, given a source document is found at `/home/user/myproject/src/main/resource/message.properties` + +... and your source document root (src-dir option) is set to "." + +... Your zanata.xml is located at `/home/user/myproject` + +... For a locale mapping defined as `zh`: + + +The following placeholders will be detected: + +``` +{path} = 'src/main/resource' +{filename} = 'message' +{locale} = 'zh-CN' +{locale\_with\_underscore} = 'zh_CN' +{extension} = 'properties' +``` + + +The mapping rules configuration is optional in zanata.xml. If not specified, standard rules are applied according to your [project type](https://github.com/zanata/zanata-server/wiki/Project-Types). + + 1. gettext: `{path}/{locale_with_underscore}.po` + 1. podir: `{locale}/{path}/{filename}.po` + 1. properties: `{path}/{filename}_{locale_with_underscore}.{extension}` + 1. utf8properties: `{path}/{filename}_{locale_with_underscore}.{extension}` + 1. xliff: `{path}/{filename}_{locale_with_underscore}.{extension}` + 1. xml: `{path}/{filename}_{locale_with_underscore}.{extension}` + 1. file: `{locale}/{path}/{filename}.{extension}` + +--- + +[Old instructions](https://github.com/zanata/zanata-server/wiki/Client-Configuration) diff --git a/docs/images/302-user-settings.png b/docs/images/302-user-settings.png new file mode 100644 index 00000000..451b4aab Binary files /dev/null and b/docs/images/302-user-settings.png differ diff --git a/docs/images/350-version-config-file.png b/docs/images/350-version-config-file.png new file mode 100644 index 00000000..5f8262ae Binary files /dev/null and b/docs/images/350-version-config-file.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..0e67da93 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,34 @@ +Zanata Command line Client +============= + +The Zanata Command line client (CLI) is the perfect way to connect to a Zanata server to +push and pull content. + +Features +-------- + +- Initialize a Translation project from the command line. +- Push source content to the Zanata server. +- Pull translated content from the Zanata server. + +Installation +------------ + +For installation instructions please see the [Installation Section](installation) + +Contribute +---------- + +- Issue Tracker: http://bugzilla.redhat.com +- Source Code: github.com/zanata/zanata-client + +Support +------- + +If you are having issues, please let us know. +We have a mailing list located at: zanata-users@redhat.com + +License +------- + +The project is licensed under the BSD license. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..bbca24e0 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,43 @@ +# Installation + +The Zanata client (zanata-cli) can be installed on most systems. Installation is easiest under Fedora, other systems can use Apache Ivy for installation. Manual installation is also possible. + + +## Installation on Fedora + +If you are using Fedora, zanata-cli is available through the `yum` package manager. + +```bash +sudo yum install zanata-client +``` + +## Installation with Ivy + +The Ivy distribution of the client is a small script that will download the client the first time it is run. This distribution requires Apache Ivy to run. + +Instructions for installing Apache Ivy and the Ivy version of zanata-cli can be found at [Zanata Ivy Client on github](https://github.com/zanata/zanata-client-ivy). + +*Note:* The Ivy client will download required files the first time it is run, which may take several minutes. It will show `resolving dependencies...` while this is happening. + +## Manual Installation + +To manually install zanata-cli: + + 1. Navigate to [zanata-cli on Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.zanata%22%20AND%20a%3A%22zanata-cli%22). + 1. Download either `dist.zip` or `dist.tar.gz`. + + 1. Extract the contents of the archive to your location of choice. + 1. Create a symbolic link to the `zanata-cli` script in the bin directory of the extracted archive. e.g. from the archive directory, run `sudo ln -s bin/zanata-cli /usr/local/bin/zanata-cli`. + + 1. (optional) you can also enable tab-autocomplete for the client if you use bash as your terminal shell. This can be done by copying or linking the `zanata-cli-completion` script from the bin directory to `/etc/bash_completion.d/`. e.g. `ln -s bin/zanata-cli-completion /etc/bash_completion.d/zanata-cli-completion`. + +## Nightly Builds + +If you like to live dangerously, the client nightly relase is available. This may have newer features, but is not guaranteed to be stable. + +The latest nightly build is available as an archive that can be installed manually. To install the latest nightly build: + + 1. Open [Client nightly builds](http://repository-zanata.forge.cloudbees.com/snapshot/org/zanata/zanata-cli/). + 1. Open the directory showing the highest version number. + 1. Download either of the distributable archives (ending with `-dist.zip` or `-dist.tar.gz`). + 1. Install as per manual installation instructions above. \ No newline at end of file diff --git a/docs/maven-plugin/commands.md b/docs/maven-plugin/commands.md new file mode 100644 index 00000000..b2776835 --- /dev/null +++ b/docs/maven-plugin/commands.md @@ -0,0 +1,65 @@ +# Commands + +If your project uses Apache Maven, you can use Zanata's Maven Plugin rather than the command line client. The Maven Plugin can be used for non-Maven projects, but the same functionality is available in zanata-cli without the need to install or configure Maven. + +The following instructions assume that you have installed and configured the Zanata Maven Plugin. Instructions for installation and configuration are available at [Installing the Maven Plugin](maven-plugin/installation) and [Configuring the Maven Plugin](maven-plugin/configuration) + +## Basic Maven Plugin commands + +Commands and options for the Maven Plugin are similar to commands and options for zanata-cli, but with different syntax. + +### Help + +To see an overview of commands, use + +```bash +mvn zanata:help +``` + +and for detailed help for a particular command, use something like + +``` +mvn zanata:help -Ddetail=true -Dgoal=push +``` + +These are equivalent to commands `zanata-cli help` and `zanata-cli help push` in zanata-cli. + +*Note:* an online view of the same help information can be viewed at [Maven Plugin Reference](https://zanata.ci.cloudbees.com/job/zanata-client-site/site/zanata-maven-plugin/plugin-info.html). + +### Push + +The basic push command is + +```bash +mvn zanata:push +``` + +This will look for source documents in the location for `srcDir` specified in `pom.xml` and upload them to the server. If `srcDir` is not specified in `pom.xml`, the current directory will be used. + +The source directory can be overridden on the command line as shown here: + +```bash +mvn zanata:push -Dzanata.srcDir="src/messages" +``` + +This will look for source strings in "src/messages". + +More detail on the push command can be found at [Document Upload with Client](commands/push) + +### Pull + +The basic pull command is + +```bash +mvn zanata:pull +``` + +This will download translated documents from the server and save them in the location for `transDir` specified in `pom.xml`. If `transDir` is not specified in `pom.xml`, the current directory will be used. + +To download the source documents as well, specify pull type 'both' as shown here: + +```bash +mvn zanata:pull -Dzanata.pullType="both" +``` + +More detail on the pull command can be found at [Document Download with Client](commands/pull) diff --git a/docs/maven-plugin/configuration.md b/docs/maven-plugin/configuration.md new file mode 100644 index 00000000..f9f933b4 --- /dev/null +++ b/docs/maven-plugin/configuration.md @@ -0,0 +1,67 @@ +# Configuration + +To use the Maven Plugin, some Zanata configuration files and an installation of Apache Maven are needed. Some additional configuration will let you use a shorter command to run the Maven Plugin. + +For Apache Maven installation, see [Installing the Maven Plugin](maven-plugin/installation). + + +## Zanata Project Configuration + +The Zanata Maven plugin uses the general configuration files `zanata.ini` and `zanata.xml` in the same way as zanata-cli. For instructions on setting up these files, see [Configuring the Client](configuration). + +In addition, parameters such as source directory can be specified in `pom.xml` so that they are not needed on the command line. + + +## Command Configuration + +When Maven is installed, a verbose command can be used to run the Zanata Maven Plugin: + +```bash +mvn org.zanata:zanata-maven-plugin::help +``` + +The following instructions will allow the concise form of the command to be used instead: + +```bash +mvn zanata:help +``` + + +### Global Command Configuration + +To use the concise form of commands for any project, open `~/.m2/settings.xml` and ensure that pluginGroup `org.zanata` is present in pluginGroups: + +```xml + + ... + + org.zanata + ... + + ... + +``` + +This allows maven to use the latest version of the Zanata plugin when any `mvn zanata:*` command is run. + + +### Per-Project Command Configuration + +The plugin can be added to a single project by adding some elements to the project's `pom.xml` file. + +The following shows a build entry in `pom.xml` that will use version 3.4.0 of the Zanata plugin, and specifies the current directory (`.`) for source documents. This is equivalent to specifying the source directory on the command line as `-Dzanata.srcDir="."`. + +```xml + + + + org.zanata + zanata-maven-plugin + 3.4.0 + + . + + + + +``` diff --git a/docs/maven-plugin/installation.md b/docs/maven-plugin/installation.md new file mode 100644 index 00000000..dd4421f3 --- /dev/null +++ b/docs/maven-plugin/installation.md @@ -0,0 +1,32 @@ +# Installation + +If your project uses Apache Maven, you can use Zanata's Maven Plugin rather than the command line client. The Maven Plugin can be used for non-Maven projects, but the same functionality is available in zanata-cli without the need to install or configure Maven. + +With Maven installed, the plugin can be run in the verbose form with no additional setup, or can be set up to use the concise form globally or for a single poject. The first time a command is run, the plugin and all its dependencies will be downloaded, which may take a while. + +## Prerequisite - Install Maven + +Zanata Maven plugin requires Apache Maven to be installed. Maven can be downloaded from [The Apache Maven website](http://maven.apache.org/) or installed using your operating system's package manager (e.g. `yum install maven`). Other installation options can be found at [Zanata wiki - Maven Plugin](https://github.com/zanata/zanata-server/wiki/Zanata-Maven-Integration). + + +## Verbose Command (No Additional Setup) + +It is possible to run the Zanata plugin without any special setup once Maven is installed. + +This is done by specifying the full plugin id including version on the command line. For example, the help command can be run with: + +```bash +mvn org.zanata:zanata-maven-plugin::help +``` + +The instructions in other sections will assume that you are using the concise form of the command, so if you choose to use the verbose form you should use `mvn org.zanata:zanata-maven-plugin::` anywhere you see `mvn zanata:` in the instructions. + +## Concise Command + +Using global or per-project setup will allow the use of the concise form of the command, which would shorten the help command to: + +```bash +mvn zanata:help +``` + +See "Global Command Configuration" under [Configuring the Maven Plugin](maven-plugin/configuration) for details. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..25349569 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,19 @@ +site_name: Zanata Client +docs_dir: docs +repo_name: GitHub +repo_url: http://www.github.com/zanata/zanata-client +theme: readthedocs +# theme_dir: For custom themes + +pages: +- ['index.md', 'Home'] +- ['installation.md', 'User Guide', 'Installation'] +- ['configuration.md', 'User Guide', 'Configuration'] +- ['maven-plugin/installation.md', 'Maven Plugin', 'Installation'] +- ['maven-plugin/configuration.md', 'Maven Plugin', 'Configuration'] +- ['maven-plugin/commands.md', 'Maven Plugin', 'Commands'] +- ['commands/init.md', 'Commands'] +- ['commands/push.md', 'Commands'] +- ['commands/pull.md', 'Commands'] + +copyright: Copyright © 2015, Red Hat.