Subtitle: Translate rst-files on Github
Version and revision: V1.0
Accessible to: Novice / Beginner
Date of presentation: Released on 2016-03-29
Date of the latest revision: Revision: 2016-04-05
Contact: Hunv via Community

First of all: This manual is made for people without any knowledge of GIT. If you already know GIT, you may like to modify the files another way.

Translate manuals without installation of additional software

1. Create an Account on Github and Login

If you have no account on Github, register a new account. Login with your account on Github.

2. Open the Nethserver-Docs Repository

Open the URL https://github.com/NethServer/nethserver-docs in your Browser

3. Fork the nethserver-docs repository

Click at “Fork” in the top right of the NethServer-Docs Repository

You will be redirected to your “copy” of the NethServer-Docs Repository. You can see this copy at the top, because your username is in front of the repository name and the hint “forked from NethServer/nethserver-docs” is added. Everything else looks like in the original source.

4. Get the manual files

Click the “Download ZIP”-Button at the top right of the content table.

5. Edit files locally

To edit the files locally, change to the Download-Folder (or the destination where you saved the file) and extract the content of the zip-file. (i.e. (Windows only): right mouseclick ⇒ “Extract all”). After the extraction, open the extracted folder and change to the directory “administrator-manual” or “developer-manual”.

6.Prepare your local files

  1. If you like to create a new Language, copy the folder “en” and rename it to the short name of your language (i.e. “de” for German)
  2. If you like to create a new translationfile, that is missing in your language, go in the folder “en”, copy the original file and past it into your language-folder
  3. If you like to modify an already existing translation, continue with the next step

Only files, that are ending with “.rst” are the files, you have to translate. They are in the format of “reStructuredText”, like Wikipedia is using. More about rst is mentioned in Wikipedia: https://en.wikipedia.org/wiki/ReStructuredText

7. Translate

Open the rst-file you like to translate in your favorite Texteditor (i.e. Notepad++).
Translate the content in the files. Some recommendations:

  • Don't translate words, that are never used in the translated version (i.e. “Traffic Shaping” is never used as “Verkehrsformen” in German).
  • Translate sentence by sentence. The content of the translation is important, not that everything is translated word by word.
  • Translate everything and don't leave some stuff
  • Remind the rst-Format
    • Each Headline needs equal-signs below with the same lenght that the headline has
    • each command needs two leading spaces
    • don't Translate “.. note::”, “.. warning::” etc.
    • a :: is a linebreak. A linebreak in the text will be ignored, so you can format the text that each line is just one sentence.
    • if you don't know how to do it the right way, check the offical documentation how it looks like in the original: http://docs.nethserver.org/en/latest/

After you're done, save your file(s) and close the editor.

8. Upload to Github

Go back to Github and open the “administrator-manual” or “developer-manual”-folder on the main-page of your repository-copy.


If you added a new Language

If you added a new Language, delete all untranslated files from your local folder. After that, click on “upload files” on the top right.

Drag your local language-folder (i.e. “de”) and drop it in the area where “Drag files here to add the to your repository” is displayed. The Text will change, when your mouse moves over that area.

Wait until all files are uploaded and shown below the Drag/Drop-Area

If you added a new file or changed a file

If you added a new file or changed a file, open the languagefolder you modified a file for. Click on the “Upload files”-Button on the top right and drag'n'drop the file in the drag/drop-Area like described in Step “If you added a new Language”. In the lower area select “Commit directory to the master branch” and click on “Commit changes” after you are done and all files are uploaded and changed you like to upload or modify

9. Create Pull Request on Github

Go back to the root of your nethserver-docs-repository. Click on the green “New pull request”-Button.

Click on “Create pull request”. This will result in a request to add your files to the Repository of Nethserver-Docs and finally to the official Nethserver Documentation.

10. Delete your fork on Github (optional)

After you are finished, maybe somebody else adds more stuff to the official manual repository. To work around this issue, you have to delete your copy of the repository first before you can copy it again. To do this, click on “Settings” below the title of the repository.

Scroll down to the red “Danger Zone” and click on “Delete this repository”.

A popup will appear. Enter “nethserver-docs” and click on “I understand the consequences, delete this repository”. After you have done this step, you can start all over again.