Skip to content

E
edx-platform
Commit 77ac4158 by Sarina Canelake
Options

Merge pull request #2398 from edx/sarina/improve-translator-docs 

Improve i18n translator documentation
parents a7048f92 41b665d7
Showing with 179 additions and 69 deletions
docs/en_us/developers/source/i18n_translators_guide.rst
......@@ -8,59 +8,205 @@ are hosted at `Transifex.com <https://www.transifex.com/>`_, which provides
a web application allowing translators to write, submit, and manage their
translations.
This page explains how to get started with Transifex, and provides guidelines
This page explains how to get started with Transifex and provides guidelines
for translators to follow when executing translations. For further discussion,
we welcome you to join the `openedx-translation <https://groups.google.com/forum/#!forum/openedx-translation>`_
mailing list.
For information on the Transifex process, see the following sections:
* `Getting Started with Transifex`_
* `Guidelines for Translators`_
Getting Started with Transifex
******************************
Contributors wishing to help translate edx-platform and
associated projects can find edX translation projects on
`Transifex <https://www.transifex.com/organization/open-edx/dashboard>`_.
Follow these steps to become an Open edX translator!
1. Go to `https://www.transifex.com/signup/contributor/ <https://www.transifex.com/signup/contributor/>`_
and fill out the form to create your free Transifex account, if you don't already
have one.
You should become a translator only if you feel very confident
in both your language in English. Open edX is written in English, so all
translations will be done from English to your language.
This guide shows images from the Transifex website in English. Depending
on your browser settings, you may see the site in a different language. The
button locations will be the same.
This section contains the following subsections:
* `Signing Up For An Account`_
* `Joining A Translation Team`_
* `Joining A Review Team`_
* `How To Translate With Transifex`_
* `Requesting A New Language`_
Signing Up For An Account
=========================
Go to `https://www.transifex.com/signup/contributor/ <https://www.transifex.com/signup/contributor/>`_
and fill out the form to create your free Transifex account, if you don't already
have one.
Joining A Translation Team
==========================
1. Once you've set up your account, visit one (or more!) of the edX projects to request
to become a translator for your language.
Projects include:
* `edx-platform <https://www.transifex.com/projects/p/edx-platform/>`_
* `edx-comments-service <https://www.transifex.com/projects/p/edx-comments-service/>`_
* `edx-notifier <https://www.transifex.com/projects/p/edx-notifier/>`_
2. When you visit the project page, it looks like this. If your language is listed, click
on the name of the language to go to the language's page. Here is an example of choosing
the Japanese translation project:
.. image:: images/edx-platform-transifex-project.png
3. Once you're on the language's page, click "Join team" to become part of the translation team
for that language:
.. image:: images/join-language-team.png
Once you've joined a translation team, you can begin translating strings immediately! See the
section `Using Transifex`_.
Joining A Review Team
=====================
Optionally, you can request to become a `reviewer <http://support.transifex.com/customer/portal/articles/1167280>`_
for a language. You should do this only if you feel very confident in both your language and in English. To do this, request permission
from the project coordinator(s).
2. Once you've set up your account, visit one of the edX projects and request to become
a translator for your language.
Projects::
`edx-platform <https://www.transifex.com/projects/p/edx-platform/>_`
`edx-comments-service <https://www.transifex.com/projects/p/edx-comments-service/>`_
`edx-notifier <https://www.transifex.com/projects/p/edx-notifier/>`_
1. Click on the "Members" tab of your language:
If your language is listed, click on the language to be brought to the language's page.
Next, click "Join team" to become part of the translation team for that language.
.. image:: images/view-team-members.png
You'll see a list of all the members of your translation team.
If your language is not listed, click "Request language" to start a new translation
project for your language.
2. Click on one of the Coordinators for the language to be brought to their profile page,
where you can click the "Send message" button to email them and ask for Reviewer access:
An edX translation team member will respond to your request within a few days. Once you're
approved as a member of a translation team, you can begin translating strings!
.. image:: images/send-message-button.png
Using Transifex
===============
If the coordinator don't respond, try messaging another coordinator, or message one of the edX project maintainers.
You can find the project maintainers at the top of the main project page:
Once you are approved as a translator, you can click on any of the resources in the project
to begin translating it. For help documentation on Transifex, see the `Transifex translators
.. image:: images/project-maintainers.png
How To Translate With Transifex
===============================
Once you are a member of a translation or review team, you can click on any of the resources in
the project to begin translating it. For help documentation on Transifex, see the `Transifex translators
help desk <http://support.transifex.com/customer/portal/topics/414107-translators/articles>`_.
Before you begin, be sure you've reviewed the `Guidelines for Translators`_.
When visiting a language page, you will see a list of seven distinct resources to translate:
.. image:: images/project-resources.png
We request that you focus on translating the non-Studio resources first. That is, please first
translate and review these resources:
* messages
* mako
* django-partial
* djangojs-partial
Once the above resources are 100% translated and reviewed, move on to the Studio resources:
* mako-studio
* djangojs-studio
* django-studio
Requesting A New Language
=========================
If your language is **not** listed, click the "Request language" button on the main project page
to start a new translation project for your language:
.. image:: images/request-new-language.png
Before requesting a new language, please first make sure your language is not listed! Keep in
mind that variants of your language may exist ("Chinese" versus "Chinese-China") and these
variants may meet your needs.
An edX translation team member will respond to your request within a few days. Once your
language is approved, you will be the coordinator of the project. You can add additional
coordinators, reviewers, and translators as you wish.
Guidelines for Translators
**************************
Before you dive into translation work, please familiarize yourself with the following
3 guidelines:
* `Ask for Clarification`_
* `Working With HTML`_
* `Working With Placeholders`_
Ask for Clarification
=====================
First and foremost, if you are uncertain of how to translate a string, we strongly
encourage you to reach out to us and ask for clarification! Please join the
`openedx-translation <https://groups.google.com/forum/#!forum/openedx-translation>`_
mailing list and make a post. We can help clarify the string, and even add a note
clarifying the string, which will help translators working on other language projects.
Working With HTML
=================
Translating strings for a website like edX is more complicated than simply translating sentences
from one language to another. Strings in programs sometimes need to have data inserted into them
from one language to another. Sometimes, sentences (or "strings") will contain
`HTML markup tags <https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Introduction>`_. It
is very important to understand how to deal with HTML markup.
Do **not** alter or translate any HTML markup tags.
You should translate the text that is between the tags. HTML markup tags begin and end with ``<``
and ``>`` characters.
Spacing is especially important. Adding spaces in an HTML tag (eg changing ``</a>`` to ``</ a>``)
will break the website.
Examples::
String: "If you have a general question about {platform_name} please email
<a href="mailto:{contact_email}">{contact_email}</a>."
Good translation: "{platform_name}에 대해 일반적인 질문이 있으면
<a href="mailto:{contact_email}">{contact_email}</a>로 이메일 주십시요."
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
{contact_email}로 이메일 주십시요."
Please do not remove the HTML tags.
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
<a href="흔한:{contact_email}">{contact_email}</a>로 이메일 주십시요."
Do not translate the HTML tags. Please use the given HTML tags.
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
<b>{contact_email}</b>로 이메일 주십시요."
Do not change the HTML tags to something new. Please use the given HTML tags.
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
< a href = " mailto : {contact_email} " > {contact_email} < / a >로 이메일 주십시요."
Do not add additional spacing to the HTML tags. Please use the given HTML tags.
Working With Placeholders
=========================
Strings in programs sometimes need to have data inserted into them
before being displayed to the user. Data placeholders label the places in the string where the
data will go. Strings can also have markup like HTML included. It's very important to preserve
the placeholders and markup so that the web site will work properly.
......@@ -70,7 +216,8 @@ the proper placeholder. Please familiarize yourself with all the different forms
translation successful.
Summary Of Placeholders
=======================
-----------------------
+-------------------------+
| Placeholder Forms |
+=========================+
......@@ -82,18 +229,17 @@ Summary Of Placeholders
+-------------------------+
When dealing with placeholders, you must follow these rules:
* Do Not translate the placeholder (for example, changing ``{day}`` to ``{día}``).
* Do Not alter or remove the punctuation of the placeholder string (for example, changing a ``_`` to a ``-``).
* Do Not alter the capitalization of the placeholder string (for example, changing ``day`` to ``Day``).
* Do Not alter the spacing of the placeholder string (for example, changing ``{day}`` to ``{ day }``).
Please continue reading for more examples of each type of placeholder strings, as well as
an explanation of how to deal with HTML markup.
* **Do not** translate the placeholder (for example, changing ``{day}`` to ``{día}``).
* **Do not** alter or remove the punctuation of the placeholder string (for example, changing a ``_`` to a ``-``).
* **Do not** alter the capitalization of the placeholder string (for example, changing ``{day}`` to ``{Day}``).
* **Do not** alter the spacing of the placeholder string (for example, changing ``{day}`` to ``{ day }``).
Please continue reading for examples of each type of placeholder form inside a string.
1. Do **not** alter or translate placeholder strings in between curly braces (``{ }``). Strings
inside curly braces will be replaced with different strings while the code
is executing. Changing the content of the curly braces may cause code to break.
is executing. Changing the content of the curly braces will cause code to break.
The placeholder string inside of the braces will give you clues as to what type of data will
be presented in the final string. For example, ``{student_name}`` will be replaced with the name
......@@ -123,7 +269,7 @@ an explanation of how to deal with HTML markup.
Do not alter the placeholder string capitalization - you must use {student_name} exactly as-is.
Bad translation: "¡Bienvenido { student_name }!"
Do not add additional spacing inside the ``{}`` - you must use {student_name} exactly as-is.
Do not add additional spacing inside the {} - you must use {student_name} exactly as-is.
You may rearrange the order of these strings, depending on the requirements of your language.
For example, in English the name of the month precedes the day (January 23), wheras in Spanish,
......@@ -158,7 +304,7 @@ an explanation of how to deal with HTML markup.
Do not alter the placeholder string capitalization - you must use %(student_name)s exactly as-is.
Bad translation: "¡Bienvenido %( student_name )s!"
Do not add additional spacing inside the ``()`` - you must use %(student_name)s exactly as-is.
Do not add additional spacing inside the () - you must use %(student_name)s exactly as-is.
Bad translation: "¡Bienvenido (student_name)!"
Do not remove the '%' or 's' - you must use %(student_name)s exactly as-is.
......@@ -196,43 +342,7 @@ an explanation of how to deal with HTML markup.
Do not alter the placeholder string capitalization - you must use <%= student_name %> exactly as-is.
Bad translation: "¡Bienvenido < % = student_name % >!"
Do not add additional spacing inside the ``<%= %>`` - you must use <%= student_name %> exactly as-is.
Do not add additional spacing inside the <%= %> - you must use <%= student_name %> exactly as-is.
Bad translation: "¡Bienvenido <student_name>!"
Do not remove or change the '<%=' or '%>' - you must use <%= student_name %> exactly as-is
4. Do **not** alter or translate `HTML markup tags <https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Introduction>`_.
You should translate the text that is between the tags. HTML markup tags begin and end with ``<``
and ``>`` characters.
Spacing is especially important. Adding spaces in an HTML tag (eg changing ``</a>`` to ``</ a>``)
may break the website.
Examples::
String: "If you have a general question about {platform_name} please email
<a href="mailto:{contact_email}">{contact_email}</a>."
Good translation: "{platform_name}에 대해 일반적인 질문이 있으면
<a href="mailto:{contact_email}">{contact_email}</a>로 이메일 주십시요."
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
{contact_email}로 이메일 주십시요."
Please do not remove the HTML tags.
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
<a href="흔한:{contact_email}">{contact_email}</a>로 이메일 주십시요."
Do not translate the HTML tags. Please use the given HTML tags.
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
<b>{contact_email}</b>로 이메일 주십시요."
Do not change the HTML tags to something new. Please use the given HTML tags.
Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면
< a href = " mailto : {contact_email} " > {contact_email} < / a >로 이메일 주십시요."
Do not add additional spacing to the HTML tags. Please use the given HTML tags.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment