jMonkeyEngine-wiki/docs-wiki/modules/ROOT/pages/wiki_translation.adoc

= Wiki Translation Repositories
:author: mitm
:revnumber: 2.0
:revdate: 2020/07/12


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[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 <<ROOT:documentation.adoc#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 xref:ROOT: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 xref: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 <<changing-wiki-specific-attributes,Changing Wiki Specific Attributes>>

=== Using Atom Editor to finish

This topic assumes you have already downloaded, installed and configured the xref: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 <<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://wiki.jmonkeyengine.org]`.
..  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]`.
.  Change the link:https://docs.travis-ci.com/user/status-images/[build status link] for your repository in the README.adoc page.
+
[source]
----
image:https://travis-ci.org/jMonkeyEngine/wiki.svg?branch=master["Build Status", link="https://travis-ci.org/jMonkeyEngine/wiki"]
----

.  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://wiki.jmonkeyengine.org]` 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.
.  Change the link:https://docs.travis-ci.com/user/status-images/[build status link] for your repository in the README.adoc page.
+
[source]
----
image:https://travis-ci.org/jMonkeyEngine/wiki.svg?branch=master["Build Status", link="https://travis-ci.org/jMonkeyEngine/wiki"]
----

.  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 https://github.com/jMonkeyEngine/wiki/blob/master/docs/modules/ROOT/pages/jme3.adoc[documentation 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.