WAI/Translation Instructions

From W3C Wiki
< WAI
Jump to: navigation, search

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 titles such as "Summary" in {% include box.html type="start" title="Summary" class="" %}

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.

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 or word processing 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. To see the preview, you need to submit a pull request.

To check your work in the preview as you go along, you can submit the pull request and update it as you are working on it. Please start the pull request title with "[IN-PROGRESS]" so we know it's not ready yet. (We won't act on the pull request until we get notification from you that it is ready for review or completed per below.)

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

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

Preview ready.png

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 "Completed" (after it is reviewed and ready for publication)

For example:

[IN-PROGRESS] Spanish - Accessibility Principles
[Ready for Review] Spanish - Accessibility Principles
[Completed] Spanish - Accessibility Principles

(After internal checks are done, WAI Staff will use [ready to publish] :-)

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 Front-matter

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

  • 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.
translators: 
- name: "Your Name"
contributors:
- name: "Other Name"
- name: "Other Name"

Translations Ready for Review

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

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 along with 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 missing text (like alt text), link accuracy, and formatting issues. 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 helps spot potential issues)