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

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.

General instructions for front matter

2.1. Update the following front matter values:

lang

last_updated

path (below github)

permalink

footer (not always present)

2.2. Add translators & contributors names.

After last_updated, add these lines, depending on how many translators there are and if there are contributors.

Policy for names and links is introduced in Translating WAI Resources.

Or, if the lines are there with “#” before them to comment them out: delete the # and the space.

Updated Example

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:

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

Make sure to:

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

Videos & 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 public-wai-translations@w3.org 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.

Back to Top