How to engage with the i18n WG for assistance and reviews

Prelims

1. 'Spec WG' means a WG that is developing a spec that i18n will review, eg. the CSS WG, or Timed Text WG.
2. Please touch the exhibits! Take a peek at the stuff behind the links as we go through. Most pictures link to a page, or a larger version of the picture.

When do we do reviews?

1. Any time you have a question.
2. FPWD !
   • Quality approach: early detection of issues -> lower overall non-conformance costs.
   • Sometimes we ask for changes that:
   • • need to be thought about early in the process of developing a spec, or
     • that need plenty of time for discussion and exploration.
3. At least 3 months before CR.
4. Why so long? Steps in a review:
   1. schedule the spec for review, taking into account other reviews and other work
   2. learn what the spec is about
      – the more examples the better!
      – tutorials and walk-throughs much appreciated
      – please describe/summarise algorithmic text alongside the algorithm
   3. read the spec and look for potential issues
   4. raise and discuss the findings internally to the i18n WG
   5. raise issues on the 'Spec WG' repo/email
   6. discuss, inform, wait, negotiate, track comments
      – this is often where the real work begins!

How do we find what needs reviewing?

1. Addison (i18n WG Chair) tracks public-review-announce.
2. People contact us.
   – please write to www-international, rather than contacting xfq or Addison!
3. I18n WG folks track a few lists as individuals.
4. PLH's milestones tracker
   • i18n can see in advance what's likely to be coming
   • Staff contacts need to keep the milestones up to date
   • We have requested a few changes:
     • We have asked for milestones for start of wide review.
     • An error should be raised if start is less than 2/3 months before CR.
     • However it would be nice to have push notifications to one of our mailing lists.

How to ask us to review a spec

1. See the Request a review page, then raise a GitHub issue.
2. You can find this from the i18n home page.

   Click on "Request a review", and follow the advice of the page you are taken to.

   

3. Don't just write to Addison or xfq, please.

The review radar

• We track reviews using our Review Radar, which is publicly accessible.

  

• Staff contacts and chairs can find the status of their specs there.
• (Btw, if you're not familiar with this tool, it's great for managing pipelines because you can move things in real time during a telecon!)

Doing a self-review

• Saves time – your's and our's.
• Can be done early on
  – we recommend it around FPWD,
  – and just before requesting a wide review.

• Run through the Short i18n review checklist.
  Identifies various aspects of a spec that may need internationalization review, and points to more a detailed checklist for relevant items.

  

• Work through the detailed checklist & set of guidelines called Internationalization Best Practices for Spec Developers.
• Both of the above link to (or contain) explanations and pages that help you understand the guidelines.
• Creating a review checklist you can annotate.
  • Go to https://www.w3.org/TR/international-specs/#ghChecklist
  • Follow the steps for each section that is relevant to your spec to generate an up-to-date copy of our spec review checklist
  • Create an issue in your github repo and paste the code into it.
  • Work through the checklist and annotate it.
  • Here's an example:

    

• Note: this checklist is ongoing work - it doesn't include everything, by any means - we add to it when we can. It's also negotiable - some items may not be relevant for your spec, some guidelines may need refinement. As the pirate said, these "be more what you'd call guidelines than actual rules".

Lifecycle of an i18n spec comment

• We have a set of instructions for reviewers.
• We have a Github repo that tracks issues which we believe are not resolved.
  • Each tracker issue basically just points to the issue that we sent to the Spec WG.
  • Actually, we use a different interface most of the time.

    

  • This moves most recently changed tracker issues to the top of the page.
  • We can also generate lists of issues that are pending (ie. yet to be sent), or potentially closeable – see the bottom of that page.
• Steps in the process of raising an i18n review comment:
  1. an i18n reviewer raises an issue in our tracker with a Pending label
  2. that person notifies the i18n WG that they want to send one or more comments to the Spec WG
  3. the i18n WG ok's forwarding or objects, usually during around a telecon
  4. the reviewer removes the Pending label & raises issues on the repo/bugzilla/mailing-list of the Spec WG
  5. xfq sets up a notification webhook in the Spec WG's repo, and sets an i18n-needs-resolution label for each issue raised
  6. when the issue is created, or gets an i18n-needs-resolution label, or receives new comments, or is closed, a notification is sent to www-international
     • notifications are sent once a day as digests, however i18n folks are often subscribed to the issue too
     • in the archive they are plain text, but in your mailbox they can be formatted as html

       

  7. track the issues and discuss
  8. once the Spec WG provides a fix they may close the issue, but our tracker issue remains open until we have checked the fix and concur.
• we actually set up two labels in the Spec WG repo: (a) i18n-needs-resolution (b) i18n-tracker

  (b) is applied to something we've noticed and want to track, but the Spec WG doesn't need us to confirm agreement with the resolution.

  We may, however, convert a tracked issue to a comment at some point in time.

• HINT: the Spec WG can ping the i18n folks to get help by applying the i18n-tracker label to an issue or creating a new issue with that label – the i18n WG will be notified via the daily digest.

More on notifications

• You can ask xfq or Dom for instructions about how to set up notifications for yourself
• The digests were so well liked by the i18n folks, that we also get a weekly digest, a day before the weekly telecon.

Take-aways for Chairs & Staff Contacts

1. Encourage your group to do a self review around the time of the FPWD, then let us know the result.
2. REQUEST AN i18n REVIEW AT LEAST 2-3 MONTHS BEFORE YOU GO TO CR !!
3. Use the i18n-tracker label to bring our attention to issues in your repo (but don't change the i18n-needs-resolution labels).
4. Encourage your group to add examples and tutorials to the spec - they really help us review more effectively.
   We also welcome high level walk throughs, and may be able to accomodate those via telecons.
   And please add descriptions to algorithms, so we can get the gist quickly.
5. Keep milestones up to date at https://w3c.github.io/spec-dashboard/report.html
6. If you can't remember how to contact us for review, remember that you can find it from the i18n home page at w3.org/International/.
7. I added some links for i18n horizontal reviews to The Guide.

Recent changes

• 21 May 2024: Various editorial and formatting fixes and link updates.
• 3 April 2019: Added information about the short review checklist.