Added wiki translation doc.

src/docs/asciidoc/wiki/wiki_translation.adoc

@@ -0,0 +1,220 @@
+= Wiki Translation Repositories
+:author: mitm
+:revnumber:
+:revdate: 2017-09-08T23:24:11.262Z
+:relfileprefix: ../
+:imagesdir: ..
+:experimental:
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
+
+
+Official translations of the wiki are not practical due to varying dialects, dodgy translator programs, and the increased workload needed to officially support the translations. A different approach is to have monkeys, who wish to contribute to the community, run their own translation of the wiki.
+
+This tutorial will go into the details of how to setup a copy of the wiki on link:https://github.com/[GitHub] that looks and feels like the official wiki, including link:https://github.com/marketplace/travis-ci/plan/MDIyOk1hcmtldHBsYWNlTGlzdGluZ1BsYW43MA==#pricing-and-setup[Travis-CI] automatically converting your AsciiDoc content to HTML, then publishing those files on each commit.
+
+You are not required to translate every page or even mirror changes to the official wiki. What is required is a linked wiki be robust enough to actually help other monkeys and that the content is kept current. If it's deemed worthy, a link to your repository, whether its stored on your own domain or not, will be added to the main page of the wiki under the <<documentation#languages#,Languages>> topic.
+
+[WARNING]
+====
+Although this is a tutorial on setting up and configuring your own copy of the official wiki, you still must adhere to the <<bsd_license.adoc#,jMonkeyEngine licensing>>.
+
+This includes the use of a domain name that includes the jMonkeyEngine name.
+====
+
+
+
+== Prerequisites
+
+For this tutorial you can either setup with Git, or the Atom Editor, which uses basic GitHub commands by default. You will be *loosely* implementing the instructions from link:https://github.com/steveklabnik/automatically_update_github_pages_with_travis_example[Steve Klabnik].
+
+You will need to meet these requirements to continue:
+
+*  A link:https://github.com/[GitHub] account.
+*  Either link:https://help.github.com/articles/set-up-git/[Git] or the <<wiki/atom_editor.adoc#,Atom Editor>> installed on your system.
+
+NOTE: The Atom editor also has a link:https://atom.io/packages/git-plus[Git Plus] package that uses Git if it's already on your system. Open `menu:File[Settings]` and enter "`git`" into the search box to locate and install.
+
+[TIP]
+====
+For a list of git commands, use one of these:
+
+*  link:https://services.github.com/on-demand/resources/cheatsheets/[Git Cheat Sheets]
+*  link:http://rogerdudler.github.io/git-guide/[git - the simple guide]
+
+See also Travis-CI:
+
+*  link:https://docs.travis-ci.com/user/getting-started/[Getting Started]
+====
+
+== GitHub/Travis CI Setup
+
+This topic applies to both Git and the Atom Editor. You must do this before you do anything else.
+
+.Github
+.  Create a link:https://help.github.com/articles/creating-a-new-repository/[new repository] on link:https://github.com/[github.com] for your wiki. (NOT a fork)
+..   Enter a unique name for your repository.
+.  After your repository has been created, you will need to add a new "`gh-pages`" link:https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/[branch].
+..  This will automatically setup your repository for compiling "`gh-pages`".
+..  After creating the "`gh-pages`" branch, from your repositories main page, click the icon:cog[]  btn:[Settings] link and scroll down to the "`GitHub Pages`" panel for more configuration options and to see your sites new URL.
++
+[NOTE]
+====
+There are two URLs you will need for configuration.
+
+*  Your `*gh-pages*` URL: pass:[https://username.github.io/repo-name/]
+*  Your `*repository*` URL: pass:[https://github.com/username/repo-name]
+
+This is how they will be referred to in this tutorial.
+====
+
+.  Setup GH_TOKEN variable:
+..  You need to generate a link:https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/[GH_TOKEN] in github.com, and set up Environment Variables in travis-ci.org or travis-ci.com, depending on whether your repository is public or not. This variable will be used in the deploy_ghpages.sh file.
+..  Describe it however you wish and then you will need to check some boxes. Check these ones:
+
+* [x]  public_repo
++
+--
+If your repository is private, you can set repo instead.
+
+GitHub will create the token and show a page with the value.
+
+WARNING: *THIS IS THE ONLY TIME YOU GET TO SEE THIS SO DON'T CLICK AWAY IMMEDIATELY!*
+
+You will need to copy this token into someplace you trust. It'll never be shown to you after this time, so it's important to double-check your work. You can always regenerate a new token, but then you will have to change any script or apps that use it.
+--
+
+.Travis CI
+.  Click your name icon and select `menu:Settings[Billing>Marketplace]` or the "`Marketplace`" link at the top of the page header.
+.  Click the "Travis-CI" link. If you don't see one listed, find it using the search box.
+.  Scroll to the bottom of the page and under "`Pricing and setup`" select the "`Open Source`" option if this is a public_repo or the payment plan of your choice.
+..  When ready, select the btn:[Install] button.
+..  Click through until you are redirected to the Travis-Ci website.
+.  On Travis-CI, flick the repository switch on for your gh-pages project.
++
+TIP: You can’t see your project on the list? Click on the Sync account button (top right) and it should be OK.
+
+.  Click the icon:cog[]  cog to go to the settings tab and configure it.
+..  Check some options on General:
+...  check the Build only if .travis.yml is present option.
+...  check the Build pushed options.
+..  Create some Environment Variables that will be used in .travis.yml file:
+...  GH_TOKEN: the token created on previous step.
++
+WARNING: Uncheck the Display value in build log option. This is the default action.
+
+=== Using Git Command Line to finish
+
+.  Clone the link:https://github.com/jMonkeyEngine/wiki[wiki] or your fork of the wiki and your new repository. Cloning and pushing takes some time due to the size of the wiki. Be patient.
++
+[source]
+----
+$ git clone https://github.com/jMonkeyEngine/wiki.git
+$ git clone https://github.com/user/repository.git
+$ cd repository
+$ git checkout master
+----
+
+.  Copy everything from the localized wiki repository to the localized new repository, especially these files:
+..  .travis.yml
+..  build.gradle
+..  deploy_ghpages.sh
+..  gradlew
++
+--
+`Travis CI` will execute `./gradlew asciidoctor` and `./deploy_ghpages.sh` after you push your commits.
+
+IMPORTANT: If you have ever forked the official wiki, I suggest you rename it to origin_wiki or official_wiki. Then, you can still contribute to the official wiki with that fork.
+--
+
+.  Give gradlew, deploy_ghpages.sh permission to be executed. If you don’t do this, travis-ci.org will fail, due to no permission.
++
+[source]
+----
+git update-index --chmod=+x deploy_ghpages.sh
+git update-index --chmod=+x gradlew
+git push
+----
+
+.  At this point you need to change the wiki specific attributes to complete the setup.
+*  See <<wiki/wiki_translation#Changing-Wiki-Specific-Attributes#,Changing Wiki Specific Attributes>>
+
+=== Using Atom Editor to finish
+
+This topic assumes you have already downloaded, installed and configured the <<wiki\atom_editor.adoc#,Atom Editor>> as well as cloned the  link:https://github.com/jMonkeyEngine/wiki[wiki] or your fork of the wiki and it's open in the Atom Editor.
+
+.  In the Atom Editor, select `menu:File[New Window]` or kbd:[Ctrl] + kbd:[Shift] + kbd:[N].
+..  Delete the new page that opens by default.
+.  In the new window, select `menu:Packages[Command Palette>Toggle]` or kbd:[Ctrl] + kbd:[Shift] + kbd:[P].
+..  Enter "`github`" into the search box.
+..  Select the btn:[GitHub Clone] button.
+..  Enter the URL to your `*repository*`.
+..  When ready, click the btn:[Clone] button.
+.  Copy everything from the localized wiki repository to the localized new repository, especially these files:
+..  .travis.yml
+..  build.gradle
+..  deploy_ghpages.sh
+..  gradlew
+.  Give gradlew, deploy_ghpages.sh permission to be executed. If you don’t do this, travis-ci.org will fail, due to no permission.
+..  If you use Git Plus, select `menu:Packages[Git Plus>Run]` and enter these arguments.
++
+.Using Git Plus
+[source]
+----
+git update-index --chmod=+x deploy_ghpages.sh
+git update-index --chmod=+x gradlew
+git push
+----
+
+..  If you dont have Git, then edit the travis.yml file and add this after the `branches:` command.
++
+.No Git Installed
+[source]
+----
+branches:
+  except:
+    - gh-pages
+# No git, change permissions here.
+before_install:
+ - chmod +x deploy_ghpages.sh
+ - chmod +x gradlew
+----
+
+.  At this point you need to change the wiki specific attributes to complete the setup.
+*  See <<wiki/wiki_translation#Changing-Wiki-Specific-Attributes#,Changing Wiki Specific Attributes>>
+
+=== Changing Wiki Specific Attributes
+
+[IMPORTANT]
+====
+These changes will make your copy of the wiki, including all links, 100% dependent on your `*gh-pages*` branch. You're on your own after this point so if you want selective links to still point to the official wiki, it's up to you to determine which.
+
+At minimum, you still have to change the attributes "`endpoint-url`", "`wiki_link_edit_prefix`", and "`wiki_link_create_prefix`" in the "`*build.gradle*`" file.
+====
+
+.Git CommandLine
+.  Using link:https://git-scm.com/docs/git-grep[Git Grep] or the command line editor of your choice, find and replace the following:
+..  Find the official wiki `*gh-pages*` address of `pass:[https://jmonkeyengine.github.io/wiki]`.
+..  Replace it with your `*gh-pages*` address `pass:[https://username.github.io/repo-name]`.
+..  Find the official wiki `*repository*` address of `pass:[https://github.com/jMonkeyEngine/wiki]`.
+..  Replace it with your `*repository*` address of `pass:[https://github.com/username/repo-name]`.
+.  After you have done all the above, commit and push to your wiki repository.
+
+.Atom Editor
+.  Select `menu:Find[Find in Project]` or kbd:[Ctrl] + kbd:[Shift] + kbd:[F].
+..  Enter the official wiki `*gh-pages*` address of `pass:[https://jmonkeyengine.github.io/wiki]` into the search box and then select the btn:[Find All] button.
+..  Enter your `*gh-pages*` address `pass:[https://username.github.io/repo-name]` in the "`Replace All`" box and when ready, select the btn:[Replace All] button.
+..  Enter the official wiki `*repository*` address of `pass:[https://github.com/jMonkeyEngine/wiki]` into the search box and then select the btn:[Find All] button.
+..  Enter your `*repository*` address of `pass:[https://github.com/username/repo-name]` in the "`Replace All`" box and when ready, select the btn:[Replace All] button.
+.  After you have done all the above, `menu:File[Save All]`.
+.  Open the Git panel, `menu:Packages[GitHub>Toggle Git Tab]` or kbd:[Ctrl] + kbd:[9].
+.. Stage All.
+.. Enter a "`initial commit`" message.
+.. Commit and push to your wiki repository. You can see the result after a few minutes.
+
+== Conclusion
+
+Travis should have built your copy of the wiki and moved all the .html to your "`gh-pages`" branch. If this didn't happen, then something is wrong with your setup. Examine the logs of your repository from your Travis-Ci account to help you troubleshoot where you went wrong. You can expand any of the command tags by clicking on them to get a more in-depth reveal of the logged info.
+
+When you feel your repository is ready, create a thread on the link:https://hub.jmonkeyengine.org/[forum] requesting it be added to the official wiki. If approved, create a pull request of the wiki link:https://github.com/jMonkeyEngine/wiki/blob/master/src/docs/asciidoc/documentation.adoc[main page] adding your repository link under the "`Languages`" topic.
+
+Thanks for your interest in removing the language barrier that may prevent other monkeys from learning more about the jMonkeyEngine.