Page MenuHomePhabricator

Message bundle: Extend syntax to allow for message documentation
Open, Needs TriagePublic

Description

Currently it is not possible to add documentation for messages in a message bundle.

The current syntax requires that the values for the keys always be strings.

{
  "@metadata": {
     ...
  },
  "pageTitle": "title of the page",
  "description": "description of the page",
  "translationUnits": "these are translation units",
  "footer": "footer of the page"
}

The updated syntax could be as follows:

{
  "@metadata": {
    
  },
  "pageTitle": {
    "value": "title of the page",
    "qqq": "This is the title of the page."
  },
  "description": "description of the page",
  "translationUnits": "these are translation units",
  "footer": "footer of the page"
}

In the update syntax, pageTitle key is now an object with two properties: value for the source string and qqq for the message documentation for the string.

Event Timeline

If we had this, it could help prevent bugs like T360066 and T361695. The former bug happened because an illegal title character made it into a message that forms a page name, and the latter happened because log titles need to be unique within a language. So if we could tag page name messages and log title messages as such, we could add validators that prevent bugs like that from happening again.

It would also, of course, let developers tag messages as optional or ignored right at the source, instead of us doing it in Translatewiki config files.

Example syntax with tags incorporated:

{
  "@metadata": {
    
  },
  "pageTitle": {
    "value": "title of the page",
    "qqq": "This is the title of the page.",
    "tags": [ "used-as-page-name", "part-of-set:log-titles" ]
  },
  "description": "description of the page",
  "translationUnits": "these are translation units",
  "footer": "footer of the page"
}

This task is about message bundles – message groups specified on JSON-formatted wiki pages. JSON files stored in Gerrit work differently: they already support documentation (qqq.json), and they also have some metadata, but in the translatewiki repo rather than next to the messages. (It may be worth expanding the metadata and moving in the extension repos, but not in this task.)