Try: extract strings for translation directly from the source JSON file

[oandregal]

This is an experiment to showcase an alternative approach to handle the translation of strings stored in JSON files.

Related:

• block.json block.json string extraction wp-cli/i18n-command#210
• theme.json Extract translatable strings from theme.json files wp-cli/i18n-command#224

#27380 introduced a way for extracting strings from theme.json for translation, based on the idea that having a shared intermediate file for core, gutenberg, and wp-cli would allow updating the theme.json structure without requiring changes to the code that process those strings.

Initially, the aim was to translate only presets. However, theme.json aims now to absorb more theme metadata that may need to be translated #28110 and information for translator context was added recently as well #28246 While working on adding support for translating the customTemplates titles at #28783 I found the current direction too complex to implement with the current theme.json shape.

This PR proposes an alternative: what if we marked the strings to translate directly in the source JSON file (block.json, theme.json) instead of having intermediate structures (code, i18.json file)? For familiarity, I used _x( string-to-translate, context-for-translators ) but any mark could be used.

For example, this would be a theme.json in which the color preset names and other fields are marked for translation:

{
  "settings": {
    "defaults": {
      "color": {
        "palette": [
          {
            "slug": "black",
            "color": "#000000",
            "name": "_x( Black, Color name )"
          }
        ]
      }
    }
  },
  "customTemplates": {
    "page-home": {
      "title": "_x( Page title, Context for this string )"
    }
  }
}

This PR provides a prototype that implements this direction:

• In terms of code maintainability, it's simpler: code added, code removed.
• It doesn't require any code change as those JSON structures evolve, hence it scales well to any JSON structure: can be used for any file (theme.json, block.json, etc) and field (no matter the shape of the file).

cc @swissspidy @schlessera @gziolo for thoughts.

How to test

• Look at the test_get_template_parts test.
• Alternatively, using this PR from TT1-blocks, load any editor and verify that the UI color controls still show the proper names for "Black" and "Dark Gray". DO NOT MERGE - Try: mark strings for translation theme-experiments#206

[gziolo]

"title": "_x( Page title, Context for this string )"

What if the "Page title" string needs to use "," or anything else that could cause issues?

[oandregal]

"title": "_x( Page title, Context for this string )"

What if the "Page title" string needs to use "," or anything else that could cause issues?

Yeah. Is there a more robust format we can use for this? 🤔

[gziolo]

Yeah. Is there a more robust format we can use for this? 🤔

I'm not aware of any. It's one of the reasons why we never went in this direction for block.json. You also need to take textdomain part into account. Then you need to parse the value during execution and run the translation function.

[mcsf]

Yeah. Is there a more robust format we can use for this? 🤔

Trying to create a format inside of a format is probably going to be a headache when it comes to proper sanitisation and escaping. How about leveraging the JSON format to "mark" certain properties with other properties? Rough example:

"customTemplates": {
    "page-home": {
      "_x_title": "Context for this string",
      "title": "Page title"
    }
  }

The placement of _x_title isn't relevant, as long as it's a sibling of title. The point is that it should be safer for a parser to pick up any property that looks like _x_... and decorate the corresponding property.

[oandregal]

Colocating metadata alongside the leaf node is an interesting idea. It addresses my main concern, which is how to express i18n in a way that grows with the evolution of theme.json and block.json and doesn't require changes to three different codebases (core, gutenberg, and wp-cli).

Going to close this and focus on #28783 and/or prototyping that metadata colocation as next steps.

[swissspidy]

doesn't require changes to three different codebases (core, gutenberg, and wp-cli).

To be fair, the current approach with a schema would not require changes to WP-CLI either.

[oandregal]

Yeah, I know. But it's proving difficult to generalize to things other than presets in ways that don't require the code to maintain some state as well 😣 I'll keep trying, though.