Merge pull request #37 from mattcasters/asf-site
Improving the i18n docs
diff --git a/hop-dev-manual/modules/ROOT/assets/images/hop-translator-after-start.png b/hop-dev-manual/modules/ROOT/assets/images/hop-translator-after-start.png
new file mode 100644
index 0000000..9b7bd06
--- /dev/null
+++ b/hop-dev-manual/modules/ROOT/assets/images/hop-translator-after-start.png
Binary files differ
diff --git a/hop-dev-manual/modules/ROOT/assets/images/hop-translator-save-files-dialog.png b/hop-dev-manual/modules/ROOT/assets/images/hop-translator-save-files-dialog.png
new file mode 100644
index 0000000..404d9a1
--- /dev/null
+++ b/hop-dev-manual/modules/ROOT/assets/images/hop-translator-save-files-dialog.png
Binary files differ
diff --git a/hop-dev-manual/modules/ROOT/assets/images/hop-translator-translating-a-key.png b/hop-dev-manual/modules/ROOT/assets/images/hop-translator-translating-a-key.png
new file mode 100644
index 0000000..93425c2
--- /dev/null
+++ b/hop-dev-manual/modules/ROOT/assets/images/hop-translator-translating-a-key.png
Binary files differ
diff --git a/hop-dev-manual/modules/ROOT/pages/internationalisation.adoc b/hop-dev-manual/modules/ROOT/pages/internationalisation.adoc
index 60b8aba..5f5ff8c 100644
--- a/hop-dev-manual/modules/ROOT/pages/internationalisation.adoc
+++ b/hop-dev-manual/modules/ROOT/pages/internationalisation.adoc
@@ -3,7 +3,13 @@
== Introduction
-Hop is already being used in many countries across the world where different languages are spoken. As such internationalisation represents the support for multiple languages in our software. Since it is such a long word it is typically abbreviated to i18n.
+Hop is already being used in many countries across the world where different languages are spoken. As such "internationalisation" represents the support for multiple languages in our software. Since it is such a long word it is typically abbreviated to i18n.
+
+== Translating changes source code
+
+The message bundles that contains the translations for the various parts of Hop are part of the source code. If you want to start any i18n efforts we recommend that you set up your development environment first as described here:
+
+xref:setup-dev-environment.adoc[Setting up your development environment]
== How is it configured?
@@ -119,8 +125,60 @@
* BaseMessages.getString
* "i18:
-So please give Translator a chance to pick up the i18n keys as well as the package in which they're being used.
+So please give Translator a chance to pick up the i18n keys as well as the package in which they're being used. If you think that it would be "better" to use things like clever prefixes and so on please remember that all you're doing is making sure your keys can't be found by Translator and as such are hard to translate.
+
As much as possible, define the PKG variable to the same class as the one you're working in. This will prevent message bundles from becoming too large and perhaps difficult to merge later on.
+== Using Translator
+
+To use Translator you need 2 things: the Hop source code and a recent build of Hop.
+With the latter you can start Translator like this:
+
+[source]
+----
+sh hop-translator.sh translator.xml /path/to/hop/source/code
+----
+
+After a few seconds of code-scanning you'll see the following interface:
+
+image::hop-translator-after-start.png[Hop Translator main window after start]
+
+The default locale ```en_US``` will be selected by default.
+
+=== Translating keys
+
+As an example, here is how we can translate the Hop GUI menu to Dutch:
+
+* Select the hopgui package: ```org.apache.hop.ui.hopgui````
+* Select locale ```nl_NL``` at the very top left
+* Select any of the missing ```HopGui.Menu...``` keys
+
+In the following screenshot we selected ```HopGui.Menu.Edit.Cut```:
+
+image::hop-translator-translating-a-key.png[Hop Translator main window after selecting a package and the nl_NL locale]
+
+Now we can type in the translation for "Cut selected to clipboard" and hit the Apply button.
+Finally, when we're done with all keys and packages we can use the "Save" button to make sure our efforts are not for nought:
+
+image::hop-translator-save-files-dialog.png[Hop Translator: the save files dialog]
+
+Once the files are saved you re-build Hop and test them by using the translated keys. Finally, don't forget to commit and push changes as described here: xref:setup-dev-environment.adoc[Setting up your development environment]
+
+Please reference a JIRA case and see if there aren't any already for the locale you're covering.
+
+=== Highlighting codes
+
+As you can see in the screenshot above many packages for nl_NL are highlighted. That is because there are a lot of non-translated keys in those packages:
+
+* light red: the message bundle is missing
+* the darkest gray: over 50 keys are not translated
+* dark gray: over 25 keys are not translated
+* gray: over 10 keys are not translated
+* light gray: over 5 keys are not translated
+* the lightest gray: at least one key is not translated
+
+=== Adding a new locale
+
+If you want to translate a new locale, simply add it to the translator.xml file available in the root of your Hop build.
