diff --git a/docs/en_us/developers/source/i18n_translators_guide.rst b/docs/en_us/developers/source/i18n_translators_guide.rst new file mode 100644 index 0000000000..03b5a9925a --- /dev/null +++ b/docs/en_us/developers/source/i18n_translators_guide.rst @@ -0,0 +1,238 @@ +############################## +Guidelines for Translating edX +############################## + +Open edX uses **Transifex**, an open source translation platform, to power +the translation of edX software into different languages. All translations +are hosted at `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 +for translators to follow when executing translations. For further discussion, +we welcome you to join the `openedx-translation `_ +mailing list. + +Getting Started with Transifex +****************************** + +Contributors wishing to help translate edx-platform and +associated projects can find edX translation projects on +`Transifex `_. +Follow these steps to become an Open edX translator! + +1. Go to `https://www.transifex.com/signup/contributor/ `_ + and fill out the form to create your free Transifex account, if you don't already + have one. + +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 _` + `edx-comments-service `_ + `edx-notifier `_ + + 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. + + If your language is not listed, click "Request language" to start a new translation + project for your language. + + 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! + +Using Transifex +=============== + +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 +help desk `_. + + + +Guidelines for Translators +************************** + +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 `_ +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. + +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 +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. + +Placeholders come in a few different forms. Often, they are named so that data will be placed into +the proper placeholder. Please familiarize yourself with all the different forms to make your +translation successful. + +Summary Of Placeholders +======================= ++-------------------------+ +| Placeholder Forms | ++=========================+ +| ``{student_name}`` | ++-------------------------+ +| ``%(student_name)s`` | ++-------------------------+ +| ``<%= student_name %>`` | ++-------------------------+ + +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. + + +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. + + 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 + of a student, whereas ``{contact_email}`` will be replaced with an email address that users can + use to contact us. This will give you some context when you are translating sentences with + placeholders. + + Altering the strings includes: changing, removing, or adding punctuation, changing + the capitalization, or adding or removing given spacing. So if the placeholder string + looks like ``{placeholder_string}``, you should not change it at all, eg ``{Placeholder_String}``, + ``{placeholder-string}``, ``{ placeholder_string }``, ``{placeholder string}``. All of + these changes have the potential to break the software. + + Examples:: + + String: "Welcome back {student_name}!" + + Good translation: "¡Bienvenido {student_name}!" + + Bad translation: "¡Bienvenido {nombre de estudiente}!" + Do not translate placeholder string - You must use {student_name} exactly as-is. + + Bad translation: "¡Bienvenido {student-name}!" + Do not alter the placeholder string punctuation - you must use {student_name} exactly as-is. + + Bad translation: "¡Bienvenido {Student_Name}!" + 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. + + 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, + the day precedes the month (23 de enero). + + Example:: + + String: "Today is {month} {day}." + + Good translation: "Hoy es {day} de {month}." + + +2. Do **not** alter or translate placeholder strings that begin with a ``%``, then have a string + inside parenthesis, and then conclude with an 's' or 'd'. You must preserve the whole form. + + As in the previous example, you must not add, change, or remove punctuation, change capitalization, + or add in new spacing. + + Examples:: + + String: "Welcome back %(student_name)s!" + + Good translation: "¡Bienvenido %(student_name)s!" + + Bad translation: "¡Bienvenido %(nombre de estudiente)s!" + Do not translate placeholder strings - You must use %(student_name)s exactly as-is. + + Bad translation: "¡Bienvenido %(student-name)s!" + Do not alter the placeholder string punctuation - you must use %(student_name)s exactly as-is. + + Bad translation: "¡Bienvenido %(Student_Name)s!" + 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. + + Bad translation: "¡Bienvenido (student_name)!" + Do not remove the '%' or 's' - you must use %(student_name)s 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, + the day precedes the month (23 de enero). + + Example:: + + String: "Today is %(month)s %(day)d." + + Good translation: "Hoy es %(day)d de %(month)s." + + +3. Do **not** alter or translate placeholder strings that appear within a ``<%= %>`` block. Placeholder + strings in this format look like this: ``<%= student_name %>``. + + As in the previous examples, you must not add, change, or remove punctuation, change capitalization, + or add in new spacing. + + Examples:: + + String: "Welcome back <%= student_name %>!" + + Good translation: "¡Bienvenido <%= student_name %>!" + + Bad translation: "¡Bienvenido <%= nombre de estudiente %>!" + Do not translate placeholder strings - You must use <%= student_name %> exactly as-is. + + Bad translation: "¡Bienvenido <%= student-name %>!" + Do not alter the placeholder string punctuation - you must use <%= student_name %> exactly as-is. + + Bad translation: "¡Bienvenido <%= Student_Name %>!" + 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. + + Bad translation: "¡Bienvenido !" + Do not remove or change the '<%=' or '%>' - you must use <%= student_name %> exactly as-is + + +4. Do **not** alter or translate `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 ```` to ````) + may break the website. + + Examples:: + + String: "If you have a general question about {platform_name} please email + {contact_email}." + + Good translation: "{platform_name}에 대해 일반적인 질문이 있으면 + {contact_email}로 이메일 주십시요." + + Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면 + {contact_email}로 이메일 주십시요." + + Please do not remove the HTML tags. + + Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면 + {contact_email}로 이메일 주십시요." + + Do not translate the HTML tags. Please use the given HTML tags. + + Bad translation: "{platform_name}에 대해 일반적인 질문이 있으면 + {contact_email}로 이메일 주십시요." + + 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. diff --git a/docs/en_us/developers/source/index.rst b/docs/en_us/developers/source/index.rst index 780bc55049..bb36a33f2a 100644 --- a/docs/en_us/developers/source/index.rst +++ b/docs/en_us/developers/source/index.rst @@ -14,6 +14,7 @@ Contents: overview.rst common-lib.rst djangoapps.rst + i18n_translators_guide.rst Indices and tables ==================