How to Translate a WAI Resource

Overview

There are 4 main technical steps to create a new WAI resource translation:

1. Create a new file

2. Update the “front matter” metadata

3. Translate the main content

4. Commit your changes and open a Pull Request

General guidance

• Do not change or adapt or add to the meaning of the English version in your translation.
  If you have suggestions for changes to the English version, submit them via GitHub or e-mail using the links in the “Help improve this page” box near the bottom of the page.
• Before starting, find the relevant “language tag” from the Language Subtag Registry . You will use it many times during the translation.
• The markdown files are very sensitive to indentation, commas, quotes, and special characters. We recommend that you use a markdown editor or a simple text editor (including GitHub interface) — and not a document editor like Microsoft Word that often changes quotes and indentation.
• Some resources have specific instructions. Please take a look at Resource-Specific Translation Instructions to see if this applies to your targeted resource, and follow these additional instructions if it does.
• If you wish to translate the WCAG-EM Report Tool, please read this specific guidance , as different steps have to be followed.

Initial step: Declare your intent

In accordance with the WAI Translations process, please always declare your intent and wait for reply from WAI team before starting a translation.

Step 1: Create a new file

Duplicate the file used by the original version, with the language shortcode added to the middle of the filename, as follows:

Step 2: Update the “front matter” metadata

At the top of WAI website files are some metadata, also known as “front matter”.

Your first step into the file is to update this section.

2.1. Update the following front matter values:

lang

• Replace the original value (en) with the language shortcode of your translation.

path (below github)

• Add the language shortcode at the middle of the filename.

permalink

• Add the language shortcode at the end of the permalink, with no / at the end.

footer (not always present)

• If this attribute is present, translate its content.

2.2. Add translation information

After last_updated (that corresponds to the date of the English version), add these lines:

translation – last_updated

• Change last_updated: 2000-00-00 to the date you finish the translation.
  Use the format: YYYY-MM-DD (with month in the middle).

translators and contributors

• Add information depending on how many translators there are, and if there are contributors. Policy for names and links is introduced in Translating WAI Resources.
• If the lines are present and commented out with “# “ before: delete the # and the space.

Follow additional inline instructions

Many resources have inline instructions in the front matter (after the “#” character).

Please follow these instructions. It will help you know what to translate/update and what to not change.

Step 3: Translate main content

Markdown/Code

Please leave the code, HTML, and markdown as is without changing it.

Make sure to:

• Translate titles in the markdown, such as “Summary” in:

• Translate image alternative text, such as “mouse crossed out” in:

• Make sure that the quote marks stay as is, and are not converted to “smart quotes” by word processing software.

Links

Most links are formatted with single or double brackets and parentheses; for example:

Make sure to:

• Keep brackets and parentheses together, with no space between the closing ] and the opening (.
• Keep double [[ or single brackets [ as they are.
• Translate the text in the links, including document titles.
• Do not manually add (in English), even for external links.

Links to W3C standards

If an Authorized Translation of a W3C standard has been published in your language, please point to the translated version.

Example:

- [Le standard WCAG 2.0](https://www.w3.org/Translations/WCAG20-fr/)
- [Le standard WCAG 2.1](https://www.w3.org/Translations/WCAG21-fr/)

If not, translate the link text but keep the link to the English version.

Example:

- [Le standard WCAG 2.2](https://www.w3.org/TR/WCAG22//)

Specific wording

• Check other translations in your language to see how similar words and concepts have been translated. In particular, Authorized Translations have had significant review and input.
• Read the General Translation Glossary and see if there is a glossary for your language .
• Consider different dialects. Where possible, the translation should use words and phrases that will be best understood across different areas.

Videos & Images

• If the page has videos, refer to How to Create Translated Video Subtitles and Descriptions
• If the page has images with text, refer to How to Translate Images

Step 4: Commit your changes and open a Pull Request

Commit your changes and follow instructions in Step-by-Step Guide to Translating WAI Resources.

We are here to help

If you have any questions about the translation, please report them in the related GitHub issue so that WAI team and other volunteers can help. Alternatively, send an e-mail to the publicly-archived [email protected] mailing-list.

We are happy to help you decide on the best translated wording by sharing the considerations and nuances that went into choosing the wording for the English page.