WAI/Translation Instructions

From W3C Wiki
< WAI


NOTE: This content is updated at https://www.w3.org/WAI/about/translating/

old, outdated info below

First steps and general information is in Translating WAI Resources.

This page has specific instructions for after you receive an e-mail from WAI staff that the resource is ready to be translated.

Please let us know any questions or suggestions you have!

Important Translation Guidance

Important:

  • 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.

Markdown/Code:

  • Please leave the code, HTML, and markdown as is without changing it.
  • Most links are formatted with single or double brackets and parentheses; for example:
    [text that is linked](/path/filename/)
    [[Title of WAI Page]](/path/filename/)
    Make sure to:
    • Keep these 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.
  • Translate titles in the markdown such as "Summary" in {% include box.html type="start" title="Summary" class="" %}
  • Make sure that the quote marks stay as is, and are not converted to "smart quotes" by word processing software.

Text Editor:

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 — and not a document editor like Microsoft Word that often changes quotes and indentation.

Tips & Glossary:

Resource-Specific Information:

See if there are Translation Notes for the resource you are translating.

  • Go to the page on the WAI website.
  • Near the bottom, click the "New GitHub Issue" button.
  • Click on the “Code” tab/link (before the selected "Issues" near the top left of the window).
  • Scroll down to the "README.md" box.
  • Read the "Translation Notes".

Ask!

If you have any questions about the translation, please e-mail them to public-wai-translations@w3.org. 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.

Video Subtitles

If the page you are translating has videos, set the video subtitles to default to your language.

  1. Delete |default from: captions="W3C_INTRO_SFHI.vtt|en|default" so it's:
    captions="W3C_INTRO_SFHI.vtt|en"
  2. Add |default after your language vtt. For example:
    ,W3C_INTRO_SFHI.ar.vtt|ar|default,

Highlighted Version

Some resources we put in a Google Doc with the translation instructions and the text to translate highlighted. (Video Intro, Standards Overview, Principles, Components)

To get the file from Google Docs, you can select File > Download as...
You probably want to select one of the first options to keep the highlighting.

If you will use GitHub: It's the same content as in GitHub — except for the extra instructions at the beginning. Therefore, you can save the Google Doc locally, translate the Google Doc, delete the instructions before the "---", fork the GitHub repo, and replace the text with your translation.

GitHub

We encourage you to use GitHub if you are comfortable with it.
If not, we can work with text files.

Getting to the repository: Near the bottom of each page on the WAI website, there is a "Help improve this page" box. The middle button is "Fork & Edit in GitHub". That gets you to the repository.

Create New File

You can fork and edit from the main repository.

  • "Create a new file" with the language shortcode added to the middle of the filename, as follows:
English file: index.md
Korean file: index.ko.md
  • You can copy everything from index.md and use that to start your translation.

Preview

We have enabled a preview with Netlify so you can check your file and make edits. To see the preview, you need to submit a pull request. Please start the pull request title with "[IN-PROGRESS]" so we know it's not ready for review yet. Make it a draft pull request while you are working on it.

To set it as a draft pull request:

1. In the "Create pull request" button, select the drop-down arrow.

2. In the drop-down options, select "Create draft pull request".

The button changes to "Draft pull request".

3. Select the "Draft pull request" button.

After you submit the pull request, it will create a preview. At first it will say "Some checks haven't completed yet.".

  • After a few minutes, the box will say "All checks have passed"
  • The last line is "deploy/netlify — Deploy preview ready!"
    At the end of that line, click the "Details" link to see your preview.

If you get a message that the checks have failed, it is probably because there is a problem in the markup.

  • Click on that last "Details" link.
    It will open up a "Deploy log".
  • Skim through the log until you see information about what failed (in red text).
  • If you're not able to fix the issue, let us know, and we can help. :-)

Pull Request Status & Title

To help us keep track of the pull requests and status, please use this for your Pull Request Titles: 

[status] Language - Resource Title

with status of "IN-PROGRESS" or "Ready for Review" or "Ready to Publish" (after it is reviewed and ready for publication)

For example: 

[IN-PROGRESS] Spanish - Accessibility Principles
[Ready for Review] Spanish - Accessibility Principles
[Ready to Publish] Spanish - Accessibility Principles

Front-matter / Meta-data

This is the information at the top of the page that starts: 

---
Title: "...

We are trying different approaches; thus there are different instructions below. Please let us know what works best for you, and any questions or suggestions that you have.

1. Comments Inline for Front-matter

The following resources currently have comments inline for what to translate and change:

2. Instructions Here for Frontmatter

These instructions apply to all other resources not listed under "1. Comments Inline for Front-matter" above.

  • Set the language code:
  • Change "last_updated: 2000-00-00" to the date you finish the translation. Use the format: YYYY-MM-DD (with month in the middle).
    (Do not change the dates in the footer section.)
  • After last_updated, add these lines, depending on how many translator there are and if there are contributors. Or, if the lines are there with "#" before them to comment them out, delete the # and the space.
translators: 
- name: "Your Name"
contributors:
- name: "Other Name"
- name: "Other Name"
  • Do not change the dates after footer >. Those dates should be the same in your translation as in the English version.

Translations Ready for Review

Before you submit your translation for review, please check everything listed in
Reviewer Guidance below

Translations will be reviewed before they are published.

To let others know that your translation is ready for review, please send e-mail to public-wai-translations@w3.org with subject: 

  [Language] Request for Review – [resource title]
  • If you're using GitHub, include:
    • link to the preview
    • link to the pull request
  • If you are not using GitHub, attach your translation to the e-mail.

Include: 

When published, it will be available at: [uri/language-code]

The URI is the same as the English page + the language code at the end. For example:
https://www.w3.org/WAI/standards-guidelines/ko (This is for later readers of the list archives. After we close the pull request, the preview won't be available and we want readers to find your published version. :-)

If you know people who might review the resource (for example, other translators in your language):

  • It is usually best to also send the e-mail directly to other translators in your language so they don't miss it on the list. :-)
    And/or mention them in the GitHub pull request so they get notification.
  • If others have already reviewed your translation (and are OK being listed as a reviewer), include their names in the GitHub pull request "Conversation", or in the e-mail.

When it's Ready for Publication

When your translation has been sufficiently reviewed and you have addressed comments, let us know that it is done.
Please send e-mail to public-wai-translations@w3.org with subject: 

  Completed Translation – [language code] – [resource title]
  • If you're using GitHub, include a link to the pull request.
  • If you are not using GitHub, attach your translation to the e-mail.

Include: 

When published, it will be available at: [uri/language-code]

The URI is the same as the English page + the language code at the end. For example:
https://www.w3.org/WAI/standards-guidelines/ko (This is for later readers of the list archives. After we close the pull request, the preview won't be available and we want readers to find your published version. :-)

If you want to include a link to information about you, per the policy at https://www.w3.org/WAI/about/translating/#links, include the link in the e-mail.

Remember to let us know about reviewers per above.



Reviewer Guidance

How to add comments to draft translation in GitHub - a <6 minute video:
* on YouTube
* on Zoom (unedited captions)

Initial things to check

  1. The language codes are correct, per frontmatter above
  2. The information in the "About this translation" box is correct. (If translator or contributor names are missing, it's because they are still commented out. Delete the hashmark and space (# ) before the lines.) There should be 5 lines, for example:
    1. Cette traduction faite par des volontaires peut ne pas refléter les intentions de l’original en anglais.
    2. {icon of check in circle} Traduction à jour par rapport à la version anglaise.
    3. Traduction mise à jour : 2019-07-15. Version anglaise mise à jour le : 2019-06-05.
      [check these dates -- one is the date of the translation. the other should usually match the date in the footer]
    4. Traduction : Sylvie Duchateau.
    5. WAI remercie ces traducteurs, et accueille volontiers d’autres traductions.
  3. In the footer, the dates are the same in the English version and the translated version.
  4. There is no code showing in the rendered page.
  5. All of the text that should be translated, is actually translated.
    • Check the raw file to see if all alt text and other not-visible content is translated.
  6. The links work.
  7. In the "Help improve this page" box near the bottom, the "Fork and Edit" button works. If not, the fix is probably adding "content/" to the path. For example:
    path: content/index.es.md
  8. For any videos on the page, the [CC] defaults to the translated language. If not, the video subtitles steps above are probably missing.

For people who know the translated language

The most important thing for review is helping accurately convey the meaning from the English version in the translated language. For that, you will need to read the English version and compare it to the translation. Often is best to have them open in side-by-side windows.

A technique for proof-reading is to listen to the translation being read aloud, for example with a screen reader or text-to-speech in the operating system.

Specific wording:

  • Consider different dialects. Where possible, the translation should use words and phrases that will be best understood across different areas.
  • The translator and reviewer(s) might want to work together to consider different options for some wording. If you have any questions about the wording, please e-mail them to public-wai-translations@w3.org. 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.
  • When you decide on translation of unclear words and phrases that will likely be in other resources, feel free to add them to the Glossary for your language.

For people who do not know the translated language

You can still help with reviews by looking for things like: English text that is not translated (like alt text), link accuracy, formatting issues, and other things listed at the top of this section.

You can also help find missing content or potential issues with the specific wording. Suggestion: Compare three versions side-by-side:

  1. The English original
  2. The translation for review
  3. A machine translation of the translation back into English (of course, this will be very inaccurate, yet sometimes it still works to spot issues)

Links

Here is information on what types of links should have what format. 

This section provides background and an open issue.

The WAI website generator knows the translation status of other pages in the WAI site system ("WAI site"). Most links to pages within the WAI site start with a slash; e.g., (/standards-guidelines/wcag/)

For links to pages in the WAI site, the system will add "(in English)" in the translated language at the end of the link if the linked-to page is not translated.

If the link text is exactly the same as the linked-to page title, then the link should use [[double brackets]]. When a linked-to page is translated, the system will use the translated page's title.

For most links outside the WAI site system, we don't know if the linked to page will be translated in the future. Therefore, we initially decided to not add "(in English)" to other links.

We do know that the language will not change for W3C TR links, that is, links that start with: (https://www.w3.org/TR/...). (Translated versions of TRs are at a different URI, e.g., (https://www.w3.org/Translations/WCAG20-fr/)

[open issue]   Therefore, we could ask translators to add "(in English)" to links that go to TRs.

[open issue]   We could also change the initial decision and ask translators to add "(in English)" to all non-WAI-site links that are unlikely to be translated in the future.

[open issue]   Add your thoughts to this GitHub Issue 258.

Retrieved from "https://www.w3.org/wiki/index.php?title=WAI/Translation_Instructions&oldid=116848"