Merge branch 'integration/master' into release

Conflicts:
	pom.xml
	zanata-cli/pom.xml
	zanata-client-commands/pom.xml
	zanata-maven-plugin/pom.xml
	zanata-rest-client/pom.xml

.gitignore

@@ -4,6 +4,10 @@
 .classpath
 .project
 .settings
-*.iml
 */bin/
 test-output/
+.zanata-cache/
+
+# idea
+*.idea/
+*.iml

.travis.yml

@@ -1,12 +1,21 @@
 language: java
+
+# Use the 'true' command to avoid up-front dependency fetching, for faster builds
+# See http://docs.travis-ci.com/user/languages/java/#Dependency-Management
 install: true
-script: mvn --batch-mode --settings settings.xml test -Dgwt.validateOnly -Darquillian.jboss.home=/dev/null
+
+script: |
+  mvn test \
+    --batch-mode \
+    --settings .travis-settings.xml \
+    -Darquillian.jboss.home=/dev/null \
+    -Dgwt.validateOnly \
+    -DstaticAnalysis
+
 jdk:
   - openjdk7
   - oraclejdk7
   - oraclejdk8
 
 matrix:
   fast_finish: true
-#  allow_failures:
-#    - jdk: oraclejdk8

docs/command-hook.md

@@ -0,0 +1,38 @@
+Custom commands can be specified in zanata.xml. Custom commands can be almost any command that can run on the command line, and can be configured to run before or after a Zanata client command. This feature was added in version 3.3.0 of the CLI client and the Maven Plugin, and cannot be used in earlier versions.
+
+To specify one or more custom commands:
+
+ 1. Add a `<hooks>` element in zanata.xml within the `<config>` element.
+ 1. For each Zanata command that will have custom commands attached, add a `<hook>` element that specifies the command as an attribute.
+ 1. For each custom command to run before a Zanata command, add a `<before>` element with the command as its body.
+ 1. For each custom command to run after a Zanata command, add an `<after>` element with the command as its body.
+
+For example, the following elements within the top-level <config> element will generate a .pot file from a man page before push, clean up the generated file after push, and will generate a translated German man page after pull then remove all downloaded .po files.
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<config xmlns="http://zanata.org/namespace/config/">
+
+...
+
+  <hooks>
+    <hook command="push">
+        <before>po4a-gettextize -f man -m manpage.1 -p manpage.pot</before>
+        <after>rm -f manpage.pot</after>
+    </hook>
+    <hook command="pull">
+        <after>po4a-translate -f man -m manpage.1 -p trans/de/manpage.po -l manpage.de.1 --keep 1</after>
+        <after>rm -rf trans</after>
+    </hook>
+  </hooks>
+
+...
+
+</config>
+```
+
+Multiple commands of the same type (i.e. "before" or "after") within a hook will be run in the order that they are specified in zanata.xml. e.g. when running pull with the above config, po4a will always run before rm. If any of these commands fails, the whole operation is aborted. e.g. when running push, if po4a fails then push and rm will not be run, and if push fails then rm will not be run.
+
+Note that some commands (such as 'cd') do not work as custom commands. The ranges of commands that work and that do not work as custom commands have not yet been thoroughly investigated.
+
+The return value of each custom command is displayed after the command is run. A return value of 0 usually indicates success, and any other number usually indicates an error. Console output from custom commands is not yet displayed or logged.

docs/commands/init.md

@@ -0,0 +1,45 @@
+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.

docs/commands/pull.md

@@ -0,0 +1,41 @@
+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`.

docs/commands/push.md

@@ -0,0 +1,60 @@
+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][configuration].
+
+
+
+## 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.md]).
+
+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).

docs/configuration.md

@@ -0,0 +1,152 @@
+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](command-hook.md).
+
+## Source directory and translation directory
+
+To prevent the need to specify the source and translation directories on the command-line, they can be specified in zanata.xml. The source and translation directories are specified in the `<src-dir>` and `<trans-dir>` elements respectively, as shown below. Both paths must be relative to the directory that contains zanata.xml.
+
+```xml
+<src-dir>po</src-dir>
+<trans-dir>.</trans-dir>
+```
+
+## Locale Configuration
+
+***Note:*** Locale configuration in zanata.xml is being phased out, and this configuration will be specified on the server instead. When your project is on a server version that allows locale configuration and you have a client version that supports server locales, you should remove this configuration. Check the details in [feature request 1156236](https://bugzilla.redhat.com/show_bug.cgi?id=1156236).
+
+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
+<locales>
+  <locale>es</locale>
+  <locale>ja</locale>
+  <locale>fr</locale>
+  <locale>zh-Hant-TW</locale>
+  ...
+</locales>
+```
+
+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
+  <locale map-from='es'>es-ES</locale>
+```
+
+### 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 %}
+<!-- example rules definition in zanata.xml -->
+<rules>
+  <rule pattern="**/pot/*.pot">{locale}/{path}/{filename}.po</rule>
+  <rule pattern="**/po/*.pot">{path}/{locale_with_underscore}.po</rule>
+</rules>
+{% 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, if you have the following file structure (where `{projectRoot}` is the root directory of your project and contains zanata.xml):
+
+```
+{projectRoot}/
+              templates/messages/kdeedu/kalzium.pot
+              templates/messages/kdeedu/artikulate.pot
+              de-DE/messages/kdeedu/kalzium.po
+              de-DE/messages/keeedu/artikulate.po
+              ...
+              zanata.xml
+```
+
+Here we have two source documents (with "pot" extension) and two translation documents (with "po" extension) for the locale "de-DE".
+
+You can then use below configuration:
+{% highlight xml %}
+<src-dir>templates</src-dir>
+<trans-dir>.</trans-dir>
+<rules>
+    <rule pattern="**/*.pot">{locale}/{path}/{filename}.po</rule>
+</rules>
+{% endhighlight %}
+
+Explanation: Since you have defined `<src-dir>` as `templates`, the source document `templates/messages/kdeedu/kalzium.pot` will have its path extracted relative to `{projectRoot}/templates`, which gives the relative path `messages/kdeedu/kalzium.pot`. The relative path then will be partitioned into several tokens to form the following variables:
+
+```
+{path}						        = 'messages/kdeedu/'
+{filename}					      = 'kalzium'
+{locale}					        = 'de-DE'
+{locale_with_underscore}	= 'de_DE'
+{extension}					      = 'pot'
+```
+
+> **NOTE** the relative path `messages/kdeedu/kalzium.pot` will be the document's unique identifier inside Zanata. 
+> If you change `src-dir` setting later, e.g. to ".", which results in a change of the relative path to `templates/messages/kdeedu/kalzium.pot`, 
+> pushing again will create a new document with the new path as its unique identifier, and the old document will be considered obsolete and will not be visible to anyone. 
+> The old document's translations will not be copied to the new document automatically, but they will appear as Translation Memory matches. This can be confusing and frustrating for translators.
+
+As the rule is defined as `{locale}/{path}/{filename}.po`, for locale `de-DE`,
+
+- source file kalzium.pot's translation file will be written to or read from `{projectRoot}/de-DE/messages/kdeedu/kalzium.po`.
+- source file artikulate.pot's translation file will be written to or read from `{projectRoot}/de-DE/messages/kdeedu/artikulate.po`.
+
+You can also replace `{locale}` with `{locale_with_underscore}` if you want all your locales to use underscore instead of hyphen. e.g. `de-DE` will become `de_DE` which results in translation files written to or read from `{projectRoot}/de_DE/messages/kdeedu/kalzium.po`.
+
+The mapping rules configuration is optional in zanata.xml. If not specified, standard rules are applied according to your [project type](http://docs.zanata.org/en/latest/user-guide/projects/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}`
+