Guidance for Linguists

Linguists are Habitica contributors who help translate the website and mobile apps into different languages. The following article offers basic information as well as a series of tips and tricks that will help Linguists bring Habitica to new users from nations around the globe.

All Linguists should be fluent in the language they are translating to. It is better to have no translation than a bad translation because poor quality translations result in complaints and can damage Habitica's reputation. Please do not supply translations by using Google Translate or similar services.

This page is for translating Habitica. For information on translating the Habitica Wiki see Guidance for Linguistic Scribes.

Overview

 * Habitica organization on Transifex is the place where the translations are managed. New English strings are added by the Blacksmiths on GitHub and become source strings for translations when uploaded to Transifex. Linguists should not translate directly on GitHub.
 * There are three translation projects currently. The Habitica Transifex project is the main one. It has all the text of the Habitica site. The other two projects have the lines used by the mobile apps.
 * Each project has its own set of languages available for localization. Translators can request new languages to be added to the projects and should explain their requests on Trello. These requests are handled by the project maintainers. Mobile apps will usually have fewer languages available with new ones being added by the developers when needed.
 * Localization overview page (e.g. for Habitica project) shows the translation activity progress and the list of available languages. You will need to sign up and join the Habitica contributors team on Transifex to see more information about translations.
 * When you are logged in on Transifex and already a member of the Habitica contributors team, you can click on the project languages at the overview page to see the files for translation. For example, if you want to translate into Arabic, click on "Arabic" on the list. You will see several files named *.json (e.g., challenge.json, character.json, content.json). The names of these files and their number will vary over time.
 * These files contain variables and strings in the following form:

"_randomtitle" : "RANDOMTITLE", "variable" : "string", "variable" : "string", "variable" : "string", "variable" : "string"
 * You can view the strings online to look at the current translations. Transifex displays the variables/string tables in columns (see below). However you won't be able to translate until you join the language sub-team.
 * When you join the team translating the project, you should specify the language you will be translating into. Once you join a particular language sub-team, you will gain access to translations.

Check if there is a plan for your language

 * Go to the Translations Trello card and read the opening description of the card. Note the information there about available contributor tiers. You may also want to introduce yourself and tell people of your intention of translating. Transifex_available_languages.png
 * Go to the Habitica Transifex project and check whether your language is listed and whether the site is fully translated or not (view "all languages" and look at the green bar for yours). Check the progress on the mobile projects, too.
 * If your language is on the list for at least one of the three projects, it means that other translators have been working on the translation and you may want to help them.
 * If your language is not on the list, go back to the Trello board and start a discussion regarding your language to have someone add it for you.
 * If you have reached the conclusion that your work will enrich the current translation then proceed to the next step.

Getting started

 * Log in or sign up for Transifex by clicking on "TRY FOR FREE" in the top right corner and follow the instructions on the page.
 * Once you are logged in, go back to the Habitica Transifex project.
 * Look through the list of Project languages to make sure your language is on the list. As of June 2015, there are 70 languages to choose from. If your desired language is not there, follow the guidelines above to request a new language.
 * transifex_join_language_team.png To join the team of your language scroll up the Habitica Transifex project page and find the green button saying: "Join team". Click it and find your language in the drop-down list. Then just click "Join". You will be automatically accepted.
 * Please note: if your language is on the list of 70+ project languages, but you can't find it in the drop-down list when trying to join the team, it just means you are already a member of this team, and you simply can't rejoin it once again.
 * Now choose your language from the project languages to see the list of files available for you to translate.


 * To start translating choose and click on a ".json" file. A dialogue will open that offers you to "Translate". Click it.
 * You will get directed to a new page consisting of 3 columns:
 * The first column contains the variables. These are neither editable nor important for translating.
 * The second column is where the work takes place. You will see the original English string on top and, in the section below, you can provide your translation.
 * The third column contains some useful things like suggestions for your translation (in case something similar was translated before). You may choose to look at it or not. Generally it is useful to look at the suggestions to stick to the same vocabulary, but not required to do so.

Translating
You can now start translating. You are very unlikely to break something while doing so, so experiment with the options you are given.

Please note that you can only translate strings that have not been reviewed (i.e., new strings) as reviewed strings are considered to be correct. However, if you have a better translation for a reviewed string, you may discuss it as this kind of help is also appreciated.

Don't forget to press "Save" after each translation or hit "Save all" when the number on the latter button shows you there are some unsaved changes.

You can translate your way through all the files depending on your enthusiasm.

Review process and suggesting corrections
Once you have finished your translation work, someone will have to review it. That is usually done by a maintainer/reviewer and might take some time.

After a translated string has been reviewed, it cannot be changed except by reviewers. However, you can still help with improving translations.


 * If you think you have a better alternative for a reviewed string, open the suggestion tab and add your variant. Alternatively, you can vote for one of the variants which have been added previously by other translators if any are available.
 * Please note that reviewers/maintainers are not notified about new suggestions or votes. If you come across a line with voting results different from the reviewed version, please leave a comment tagging reviewers of your language (with @nickname in comment text). They will receive a notification about your comment.
 * If you find an incorrectly translated string and it is locked as an already reviewed one, leave a comment mentioning the reviewers as described above. If no action is taken in reasonable time, please add another comment marking it as an issue. Maintainers receive notifications about comments marked as issues, so they can review the original line, its translation, and the work of the reviewer. Your suggestion can then be discussed or implemented.

More information about the roles of contributors in Transifex teams and guidelines on becoming a reviewer can be found below (see Transifex team roles).

Glossary
The Glossary is an important feature that you should always use: it provides a list of translated words so everyone will follow them as guidelines, like a dictionary. Different people could translate the same word in different ways, so please take care of the glossary to prevent misconceptions and to help keep Habitica awesome, even in other languages.

To access it, go to the main Habitica project page on Transifex and use the "View Glossary" button on the upper right of the languages list (direct link).

Variables
Many strings have variables inside them. "sellForGold" : "Sell <%= item %> for <%= gold %> Gold", You can move variables inside the string as your language grammar demands it, but don't delete them or translate the name of the variable. Note also that variables are case-sensitive and require spaces in the right places. Variables should be reproduced exactly as they are so it's best to copy them.

Links to Wiki pages
In the strings for translation you may come across links to the Wiki pages containing additional information on some topic, e.g., Get these items faster with gems if you don't want to wait for them to drop when completing a task. Learn more about the drop system. You may change the link to the Wikia page to the corresponding page in your language, e.g. (for the French wiki), Récupérez ces objets plus vite avec des Gemmes, si vous ne voulez pas attendre de les recevoir en butin d'une tâche. Apprenez-en plus à propos du système de butin. However before you change the link please make sure that: (1) the page you are referring to exists, and (2) it gives information on the questions mentioned in this line.

Please note: when you try to save a line where a link from the original string is changed, Transifex will give two warning messages: Warning: The tag a has not been applied correctly in the translation. Warning: The following url is either missing from the translation or has been translated You may ignore these warnings in this particular case. However, please always pay attention to the text of the warning messages and consult with reviewers if needed.

Please refer to the Guidance for Linguistic Scribes if you are ready to help with translating the Wiki; your help will be much appreciated by your fellow Linguistic Scribes!

Proper nouns and capitalization
Please keep the names "Habitica" and "HabitRPG" untranslated and with exactly the same spelling (as is). This applies even in languages in which grammatical rules would normally require word endings to be adjusted or other changes to be made -- any such changes should not be made. If multiple spellings of the name were allowed, it would increase the cost of trademark protection.

The names of people, including the NPCs (Non-Playing Characters) who are real-life users of Habitica, should not be modified -- their English names should be used everywhere. The names of other characters, such as the April Fool, can be translated.

The names of quests, as well as bosses, can be translated.

Feel free to get creative with Habitican, Habiteer, Habitant, inHabitant, etc. as those are all constructions that work in English, but may not work for whatever language you're translating to.

Capitalization may be a bit tricky when translating in-game terms. Please try to respect and follow the general rules found in the Guidance for Scribes.

Language-specific Guidelines
In addition to this Guidance, translators of particular language teams may reach certain agreements about the way to deal with some linguistic issues. These agreements can arise from discussions during the translation process. Later on, each team will try to follow the internal best practices.

The topics of such agreements may include (but are not limited to):
 * the way to address the user
 * translations of specific in-game terms and their alternatives
 * translations of eggs and pets/mounts and their attributes (as each attribute should fit all pets and mounts)
 * translations of word play and tricky phrases repeated in several places
 * capitalization issues

Such agreements are not strictly imposed rules, but they help to simplify the translation process and maintain consistency. If you would like to suggest better alternatives, please first consult with other translators and reviewers before implementing the changes to the subjects of the agreements.

Please note: internal recommendations can not go against this Guidance.

The language-specific guidelines that provide extra information that cannot be found on Trello or in this Guidance are discussed at the Embassy.

Team Work and Discussions
As it has been mentioned above, translators reach some agreements and follow certain practices when translating the site and the mobile apps. Transifex provides for both general and language-specific discussion boards and announcements, but these forums are not very flexible. Having this in mind, many teams use additional places to coordinate activitites and discuss translations - the list can be found below.

In general, it may be suggested that:
 * Each language team should have a hub for discussion
 * The hub provides information about general tips or guidelines specific for the language
 * Every new translator is kindly asked to to join the hub and follow the guidelines provided by the experienced contributors
 * Every important choice (e.g. changing the translation of a specific word in all the project) should be the result of a discussion with all the team.

Some language teams prefer to use one and the same place for discussing translations of the site and the wiki. The list of such places (mostly guilds) can be found in the Guidance for Linguistic Scribes

Options in Case of Difficulties
If you are not sure about how to translate a line, you can try using one of the following options:
 * 1) Join the Aspiring Linguists guild: Commonwealth of i18n. Other translators would be glad to help you!
 * 2) Read the instructions. They can be found in the field between the original line and the text area for translation input and are given by the maintainers. Only the most confusing lines usually get special instructions.
 * 3) Check the tabs to the left of the translation field:
 * 4) *Suggestions and History - may help you if the line has just been updated and had been translated before.
 * 5) *Glossary tab - looking through the glossary may help if the reviewers of other translators have already added a term that you are not sure about.
 * 6) *Comments - translators usually try to discuss things in English, regardless of the translation language.
 * 7) General discussion - some general questions have been discussed at transifex.com/organization/habitrpg/team/6973/discussions/ but specific questions are usually discussed in native languages in corresponding threads.
 * 8) Other languages - it may be sometimes useful to look through the variants of translators belonging to the teams of other languages. You can alter translation only of the team you are assigned to; however, instead of joining a team, you can just view the results of their work. In order to do so, select one of the project languages and then choose the file you are interested in. Then, instead of hitting "Translate", choose to "View Strings Online". Moreover, when translating, it's possible to set source strings to any language you like, however it is not recommended for the sake of consistency.
 * 9) Concordance search - it may help you to search for specific terms through all of the lines in all of the files within Transifex Translation Memory of your language team.
 * 10) Transifex_advanced_filters.png Filters - can be used to show all the lines which fall under the given criteria and can prove to be way more powerful than concordance search. You can filter lines both in a single file and within all files of the project. To begin searching through all the resources, click the name of the file at the top of the list of the lines for translation, then hit "All Resources".
 * 11) GitHub - search GitHub for the key of the line you have doubts about (use the search form at the top of the page).
 * 12) Using special Habitica account for testing - you can emulate the situation in which you think the line is used.
 * 13) Submitting a comment - write your question in the comment for the line. The discussion may be more fruitful if you put other translators you know and the reviewers in @'s.
 * 14) Addressing maintainers - if none of the above helps, post another comment, this time addressing the maintainers with @'s and ask for clarification of the line.
 * 15) Marking a line as issue - if even after receiving all the suggestions you consider the line as impossible to translate to your language, leave another comment marking it as an issue.

Translating the Updated Strings
Sometimes a particular string, previously translated and even reviewed, can become untranslated. This may happen because a reviewer can delete translations to inspire translators to revisit particular strings (e.g. when a translation is absolutely wrong and it's easier to rewrite it from scratch). But more often strings lose translations because the respective source strings get updated.

If modified strings get new keys (identifiers) they are considered as new ones. The translations history and comments associated with the previous version of a string (with the old key) won't be available in the translation area anymore. However the Transifex Translation Memory can store similar strings. Please see the Suggestions tab and look up the string with the Concordance search.

If modified strings have new values, but the same keys as before, that will reset the translation area as well. However, in this case, all the previous translations can be found in the translation history of each string. Please see the "History" tab and check carefully to notice and understand what exactly has been updated in the source string.

The history of the source files updates can be found at http://oldgods.net/habitrpg/locales-diffs/ The page has the output of the  command for all the localization source files. It has been created and is maintained by a Habitica's admin Alys (Lady_Alys) to help the linguists. Please note that the "Last modified " column of the page shows the time stamp of the moment the log has been updated, not the localization source itself.

Whenever you have difficulties identifying what has changed in the source string with a recent update, first notice the key of the string and the file it belongs to. Then open the file from the list and use Ctrl+F to find the key of the string. The first line beginning with "-" will show the old version, which has been replaced with the new one, which will be the next in the log beginning with "+".

You may also want to browse the files on GitHub switching to the History or the Blame view, but the results will show the commits containing both relevant and irrelevant changes.

Translating the Mobile Apps
The official Android and iOS apps can also be translated on Transifex. Transifex has dashboards for Android and iOS.

Transifex Team Roles
Transifex translations projects are assigned to teams with contributors of different roles. When you join a team and select the language to contribute to, you become a translator belonging to a specific language sub-team. Translators can contribute to new strings with no translations and edit translations of the strings that haven’t been reviewed yet.

Apart from translators, a team can have reviewers and coordinators. A user with reviewing permissions for a specific language is considered a trusted contributor who has enough experience (including a professional one) for the title. Reviewers can be appointed by staff, team managers and language coordinators. They translate the strings and implement the quality control measures, including reviewing strings to lock them from editing and editing previously reviewed strings. Thus, translated strings can be locked from further changes by new translators for quality control reasons.

Language coordinators are reviewers responsible for appointing new reviewers for a particular language team.

You can learn more about Transifex user roles (including superior team managers, project maintainers, and admins) on Transifex documentation

Applying for reviewer (or coordinator) status
In order to become a reviewer, a translator should meet certain formal requirements:
 * Has used Habitica for more than one month;
 * Has earned some achievements;
 * Have background experience with projects related to translations / development (education, work, hobby);
 * Contributes to Transifex translations for more than one month,
 * Knows how to use Transifex tools to maintain consistency (i.e. glossary, translation memory, concordance search, batch-editing, comments, announcements, discussions, and filters - including for all the strings in all the project files);
 * Knows how to search for a specific string key on GitHub to check the uses of the data (string context, variables, links, etc.);
 * Is a team player and is always open to different opinions;
 * Follows the official Guidance and respects the language-specific community agreements and best practices.

In addition, coordinators should be ready for the following responsibilities: Please note: There is a possibility of certain languages not having a coordinator. Unless a reviewer demonstrates responsibility enough to take reasonable decisions in their chosen language, some language translations may need to function with the absence of a coordinator.
 * Account for the decisions to appoint reviewers;
 * Keep in touch with the team and the superiors, taking needed actions in a reasonable amount of time;
 * Be ready to share their opinion about application and leave the decision up to a team manager in case of doubts;
 * Contribute to the Embassy to share best practices;
 * if needed, help the Wiki admins to review the tier applications and associated contribution of the Linguistic Scribes translating the Wiki into their language.

Please note: it usually may be better to have a string not locked if translation is not perfect.

In order to apply for promotion: a translator should follow the procedure to make their application known in details by the staff and available to a certain extent for the team:
 * 1) Complete the Google Form (up-to-date link can be found on Trello) to notify the staff and the team manager in charge about your willingness to take the role of a reviewer or a coordinator for a specific language;
 * 2) Notify your team by posting to the team discussion on Transifex;
 * 3) Optional: Check the discussion boards on Transifex and post a note about your application in a team discussion with topic “Reviewer applications - your_language”. For the sake of housekeeping, one and the same topic should be used for all the applications of a particular language team (including future applications for coordinators). Be sure to select corresponding language in a drop-down list when creating a topic! (Transifex can limit the right of new translators to create new topics of team discussions - in this case wait for a team manager to create a topic for you)
 * 4) * If applicants don’t post a comment on Transifex themselves, a team manager in charge will do it for them revealing only the Transifex login of the applicant and mentioning whether the formal requirements have been met.
 * 5) * Applicants can provide as much info about themselves and their application as they want, but what is posted on Transifex discussions currently cannot be edited or deleted later. Please consider your possible privacy concerns.
 * 6) Wait for the decision and take part in reviewing other applications;
 * 7) Once the team discussion is created, team members will receive notifications about a new application automatically. They will have about two weeks to review previous public actions of the applicant and share their concerns or recommendations, if any. Information can be shared publicly in the discussion thread or sent via PM to coordinator or team manager in charge. If they receive a note for or against, they should post a comment to the discussion topic mentioning how many comments for and against have been received - to notify each other and keep discussion in one place;
 * 8) If no serious objections have been found, coordinators can appoint an applicant a reviewer as soon as they are sure in their decision. They may then post a comment on their decision to the discussion thread;
 * 9) * If coordinators cannot or don't make the decision, a team manager in charge should do so after two weeks have passed.

Contributor Tier Process
Once you have succeeded in translating a piece of Habitica, you may get a contributor tier (also known as a badge) acknowledging your help.

Tiers for help with translation are awarded to the members of the teams of languages going live: Previously a badge for reviewers was also available but the team decided to substitute it with a 1 year badge. Those who had previously obtained the reviewer badge will retain it.
 * after first personal contribution
 * after 1, 3, 6 month(s) and 1 year of constant contributing

Up-to-date instructions can always be found in the Trello card. Click the description to show its full text and find the Contributor badges section.

As of June 2016, you are asked to complete a Google Form telling the staff more about your contribution (the link is not provided here intentionally so that the Trello card is the sole source of the link). Tier requests are usually processed in batches once every few weeks.

Please note that tiers might not be awarded for poor quality translations.

Adding new translatable strings
Refer to Guidance for Blacksmiths → Translatable strings

Translating the Wiki
For information about translating the wiki, visit Guidance for Linguistic Scribes.

Guide des Linguistes Руководство_для_лингвистов