On this page

Useful links

How to review specs and raise issues

The i18n WG uses github to track comments raised against the specs of other WGs. This page outlines how WG members raise those issues. It is verbose to help beginners. Practised hands can just follow the highlighted text for reminders.

Members of the i18n Interest Group are encouraged to submit comments to www-international@w3.org. The i18n WG will then convert those comments to github issues as appropriate. If you are submitting comments to www-international, please submit one comment per email - otherwise the threads are likely to get hopelessly tangled.


You may (a) encounter a new issue while reviewing a spec or (b) come across an issue already raised by someone else in an email thread or bugzilla and feel that the i18n WG should follow that thread. In either case, follow the steps below and click on the links to see detailed instructions.

When reviewing a specification for issues related to internationalization, you can use the Short review checklist to get ideas of what to look for.

  1. Is there a label at https://github.com/w3c/i18n-activity/labels for the document in question?
    If yes, go to step 2.
    Otherwise, ask @r12a or @aphillips or to create a label, then go to step 2.
  2. Create an issue.
  3. Ask the WG to review any new issues.
  4. Once the i18n WG has reviewed the comments, notify the relevant Working Group.
  5. Monitor the email/bugzilla thread and contribute to the discussion.
  6. When the issue has been addressed, add the close? label to the issue and get agreement from the i18n WG to close it.

Create a label

  1. Labels should be the exact short-name for the document.

  2. Do not include version numbers. For example, use css-text rather than css-text-3 or css3-text. This is because if we use the same label for css3 and css4 and so on, we can spot synergies.

Create an issue

  1. Go to https://github.com/w3c/i18n-activity/issues and click on 'New Issue' at the top right of the page.

  2. Add the label for the spec.

If this is an issue you are raising (eg. via a review), follow these steps:

  1. Write a short, succinct title and add the pending label, to signify that this issue needs to be reviewed by the WG.

  2. Always start the description with information about the location of the text your comment refers to.  Do this by listing the section number and name, followed by a URI.  For example:

    6.2.1 Extended Metadata Block

    Adding the URI takes a few moments longer, but it saves lots of time later for you and others reading the issue. Where you can, use dated versions of the spec and point to the section in that dated version. This makes it easier to see the original text later.

  3. Write your comment, in as succinct and well-organised a way as possible.  It is usually helpful to quote the text you are commenting on at the beginning of your comment. For example,

    > The text elements MAY be given a lang attribute.

    We feel that you should use xml:lang for this.

Otherwise (eg. this is a thread you have noticed and want the WG to track), follow these steps:

  1. Use the subject of the email thread or the bugzilla/github issue as the title and add the track label, to signify that this issue is being tracked, rather than raised against a WG spec.

  2. Always start the description with a link to the location of the thread. This is the first email in the email thread, if an email discussion, or to the bugzilla bug or github issue page if that's where the discussion is. For an email discussion, use the thread flattener with the email subject as a parameter, eg.


  3. Ask @r12a to add an i18n-tracking tag, if available, to the issue in the repo of the target WG. This alerts them that we are tracking the issue, and helps us find issues too.

Ask the WG to review

The i18n WG should see that you have raised new issues when they receive the daily github digest. However, you should normally allow the i18n WG to comment on any new issues you want to raise, before you send the comment on to the group producing the spec, and they will need to be prompted to do that.

Send an agenda+ email several days before a weekly telecon, listing the comments you wish to send on, and asking the WG to consider them.

The telecon will allow for any objections to be aired, and give the go-ahead for comments that are ready to move to the next step.

Notify the relevant WG

If the relevant WG uses github/bugzilla:

  1. Create an issue/bug. Add www-international to the cc list for bugzilla bugs. For github, add an i18n-comment tag, or ask @r12a to add it. You'll probably also want to subscribe to notifications for a github issue.

  2. Copy over the information in the issue description to the bugzilla/github description, incorporating any changes that arise out of discussions with the i18n WG.

  3. Edit the issue at w3c/i18n-activity. Replace the initial comment with a link to the bugzilla/github page at the top of the description, such as:


    Remove the pending label from the issue.

If the relevant WG uses email for comments:

  1. Create an email and copy over the information in the issue description to the body of the email, incorporating any changes that arise out of discussions with the i18n WG.
  2. Send the email to www-international@w3.org and to the WG that produced the specification. (Note that we are NOT sending to public-i18n-core.) If appropriate, the email could be sent to one of the other IG lists instead of or in addition to www-international.)

  3. Edit the issue at w3c/i18n-activity. Replace the initial comment with a link to the email thread flattener at the top of the description along the lines of the following example:


    Remove the pending label from the issue.

Copyright © 2013 W3C ® (MIT, ERCIM, Keio, Beihang) Usage policies apply.
Content last changed 2015-09-23 19:43 GMT.