Translators using Transifex - instructions

This guide is still at the draft stage.

This guide is an updated version of the guides currently located at https://github.com/Nick-Tallguy/Nick-Tallguy.github.io/wiki/Translator-instructions-for-Transifex. When these instructions are complete they will be added to the site at http://learnosm.org/en/ and made to appear in all available languages.

Transifex

The volunteers who update LearnOSM have tried various ways to provide translations for the site, but have found that the simplest for all concerned involves using https://www.transifex.com . We are part of the Humanitarian OpenStreetMap Team https://hotosm.org/ and fall within their charitable status. Transifex kindly allow us to use their services free of charge.

The Two sites

LearnOSM

The main LearnOSM site is at http://learnosm.org/ and this is the site we are aiming to update. If you search on the internet, this is the site you will find. The modules on this site are all at 100% completion, but there are a few shortcuts in place to make sure that visitors do not get .404 errors.

There are also some translations on this site which were created before we started using Transifex. However, these modules are gradually becoming out of date, and we would like them replaced with new translations provided by you using Transifex.

The Staging or testing site

We have a second site http://nick-tallguy.github.io/ which we use for testing purposes, and which is used to allow translators to check on their progress and see how the site will appear in their language.

When we are testing things out they will appear on the staging site - but sometimes they never appear on the main LearnOSM site - not all ideas are good! If we are considering altering the layout of pages, changing the margins, or otherwise altering the site it will appear here first. Modules which are being developed are also created on the staging site and reviewed before being placed on the main site, and into Transifex for your translation.

The staging site is also there for you to check on your progress and to make sure things are formatted correctly - if you accidentally alter the ‘address’ for an image, the image will not appear on the web page, but you can review your work here, return to Transifex and fix the problem. Modules appear on the staging site when they are at least 10% translated. If you can’t find the module you’ve been translating, you’ve probably made a mistake which we hope you can correct using the information from this guide. We’re still working out the best time(s) to update the site, and at present (June 2017) the site updates at least once a day.

Getting started

  1. Go to https://www.transifex.com and log in, or create an account.
  2. Once logged in, search for HOTOSM and when you find it, request to join the team of translators
  3. HOTOSM has several different projects on Transifex and LearnOSM is not always the most urgent - for instance a new version of the Tasking Manager may need ‘strings’ translated ready for its deployment.

Joining a Language Team

Before requesting a new language, check to see which languages are already in use. It may be that your language team already exists within HOTOSM, and you just need to change your search slightly.

A language team may include; translators, reviewers and co-ordinators, or you may be the only person doing the translations for your language.

1-essential_setup txt

There are some language ‘strings’ which appear within fairly complex files needed to make LearnOSM work in your language. These strings have been put together into a file called 1-essential_setup.txt and this file should be your first priority when starting to translate LearnOSM.

Please check back on this file at intervals as well please, as we sometimes add extra strings - for instance we added a up-arrow at the bottom of each page, and it needed the language string Return to top of page.

Please note
Most, but not all of the strings are a simple translation.
However, the string:

  Replace all of this text with the one word to be   
  used in the 'language switcher', such as English,   
  Español, or Русский  

just requires you to provide the name of your language in its native tongue. This may only be one word, such as Español, or it may be more than one word.

The Beginner Section is next

Please translate the following, preferably in this order;

  1. 0200-12-31-beginner.md
  2. 0200-12-29-introduction.md
  3. 0200-12-27-start-osm.md

We will only add you’re completed translations to the main LearnOSM site once you have translated 1-essential_setup.txt, 0200-12-31-beginner.md, 0200-12-29-introduction.md, and 0200-12-27-start-osm.md

Translating a module - using 0200-12-31-beginner as an example

The first few lines of any module (apart from 1-essential_setup.txt) are instructions to the computer on how and where to display the module. If you get it wrong you may have trouble finding it, and it may cause problems elsewhere on the site - however, the problems are easily fixed - read on……

Three dashes

  ---  

The three dashes are a computer instruction - just copy them. You can use this button tx-copy-button and then click on tx-save

layout doc

  layout: doc  

is a computer instruction and should be copied across unchanged. The computer is not friendly and it will not accept any variations! The spacing must be exactly the same and it must be a colon. The safest thing to do is tx-copy-button and then click on tx-save

If your is a right to left language, such as Arabic or Persian, please add -rtl after doc so that it reads layout: doc-rtl

  permalink: /en/beginner/  

This needs altering. The /en/ part of the string is instructing the computer that this is part of the English section. You need to alter this to your language. Transifex is very helpful, if you look at your screen you will see in the web address bar something like (I’m using Hungarian in this example)

  https://www.transifex.com/hotosm/learnosm-1/translate/#hu/0200-12-31-beginnermd/51681420  

and the /#hu/ indicates that the language code is hu. You will also see this information elsewhere on your screen, looking something like this Hungarian

In this example, with the language code hu, you need to change the string to read

  permalink: /hu/beginner/  

and then save it.

Some language codes have more than two letters, such as zh_TW. Please ensure that you use your language code in exactly the same way as Transifex does. The permalink for Taiwanese is;

  permalink: /zh_TW/beginner/

lang en

  lang: en

Copy this using the tx-copy-button button, then change the /en/ part so that it reads (for Taiwanese);

  lang: zh_TW

title Beginner’s guide

  title: Beginner's guide  

Copy using the tx-copy-button button, then translate the text after title: - for Taiwanese this becomes (make sure there is a space after title:);

  title: 初學者指南  

category beginner

  category: beginner  

Copy this and do not change anything - it remains as;

  category: beginner  

cover yes

  cover: yes  

Copy this and do not change anything - it remains as;

  cover: yes  

nosearch true

  nosearch: true

Copy this and do not change anything - it remains as;

  nosearch: true

Beginner’s Guide

Translate this - for Taiwanese it becomes;

  初學者指南  

line of equals signs

Copy this and do not change anything - it remains as;

  ======

This guide shows step by step how to get started etc

Translate this in full - the full phrase in Taiwanese becomes;

  初學者指南將會導引你一步一步進入開放街圖的世界。你會學會  

how to set up an account etc

Translate the full string(s) - for Taiwanese this becomes;

  會如何申請帳號,如何使用地圖繪圖軟體,以及如何到外實地探查  

and collect information to put on the map etc

Translate the full strings until you reach the;

  [HOT Remote Mapping](/en/coordination/)  

For Taiwanese this becomes;

  [人道主義開放街圖團隊遠端製圖](/zh_TW/coordination/) 的資訊  

so that the full string for Taiwanese is;

  ,收集資訊畫到地圖上。協作章節包含了關於[人道主義開放街圖團隊遠端製圖](/zh_TW/coordination/) 的資訊  

Notice that the language code has been changed from en to zh_TW

This guide may be downloaded as etc

This guide may be downloaded as ……

LearnOSM will no longer be providing downloadable documents in this fashion. The style sheet for the site has been updated and prints may be obtained by using the menu of the web browser you are viewing the site with (Chrome, Firefox, etc..). As it would be very time consuming to have every document translated again, just because this paragraph has been removed, a software ‘fix’ has been implemented, which blanks the first instance of text beginning with a > symbol.

It is easier to replace this section of text with something like;
> This text may be ignored as it is no longer required and will not appear on the website.

Reviewed 2017 etc

  > Reviewed 2015-07-12  

in Taiwanese becomes;

  > 2015-07-12 審閱  

The > remains, Reviewed is translated, and the date is put into a format that would be understood (The date in this section uses the format)

  Year-month-day of month  

Don’t forget you can review your translations on http://nick-tallguy.github.io/en/ - this site updates roughly once a day.

0200-12-29-introduction

The first parts of this module follows the pattern you have learnt whilst translating the beginner module, but there are some additional things to be aware of.

A village in Indonesia

  ![A village in Indonesia][]

This is all computer instruction, use tx-copy-button and then click on tx-save

it remains as;

  ![A village in Indonesia][]

Sometimes you will see the image link with extra information, such as this link for the tx-save button;

  ![tx-save][]{: height="34px"}

copy it unchanged.

Please do this for all of the image links that you find whilst translating.

A village in Indonesia - the anchor

Near the end of translating a module you will find the anchor’s for the image links. The anchor for ![A village in Indonesia][] appears as;

  [A village in Indonesia]: /images/beginner/village-in-indonesia.png  

and should be copied across unchanged.

  [A village in Indonesia]: /images/beginner/village-in-indonesia.png  

Hidden Text

Some text is hidden from the normal viewers, perhaps as instructions, or more likely as something which will be expanded upon later. It takes the form of;

  <!-- all of the text between these markers is hidden -->  

You do not need to translate this text, but please copy it across unchanged (so that your translation is at 100% when you finished, and it will then be copied across to the main site. Sometimes the hidden text can be extremely large, extending over several paragraphs.

Any problems, please make contact

All of these means (and some others!) make their way to the same team.