acf-json + fields' translation

[drzraf]

I would like to use fields (defined, versioned and deployed using ACF-JSON) for various sites having different languages.
Is there a plan to handle ACF JSON when it comes to i18n fields?

A couple of hooks (are available at load-time/save-time to load/write translations (acf/prepare_field_group_for_export, NB: acf_import_field_group is missing a similar hook, only acf/update_field_group is provided) but formalize it (and why not, implement it), would be appreciated for forward-compatibility.

w3c issued a couple of guideline and draft on this topic some months ago:

• https://w3c.github.io/string-meta/
  See also:
• https://www.w3.org/2018/jsonld-cg-reports/json-ld/#string-internationalization
• https://www.w3.org/TR/international-specs/#sec_lang_mixed

[elliotcondon]

Hi @drzraf

Thanks for the topic.

ACF provides basic functionality for translating each field plus a filter for full customization.
Please take a look at the function acf_translate_field() found here:
https://github.com/AdvancedCustomFields/acf/blob/master/includes/api/api-field.php#L128

This function is called for each field (either from the DB or from JSON) and will translate the label and instructions using the 'l10n_textdomain' setting.

You can hook into the filter "acf/translate_field" to apply your own translations to the $field array.
Please let me know if you have any questions.

[drzraf]

acf_translate_field() currently relies upon __() (api-helpers.php, ~ line 4280) which will look for a translation of this string in a catalog file (cf l10n_textdomain).

But:

• translation will be found if it exists in the (compiled) catalog (.mo file)
• translation will exists in the .mo if it exists in the .po
• translation will exists in the .po if it was extracted from codebase (whether to create .po or .pot file)
• translation will be extracted if it is translatable.
  For WordPress these are function calls like __, _e (for plain PHP: *gettext() calls), for twig {% trans %}, etc etc etc.

We should not think that if that string is translatable and has been translated we will grab its value in acf_translate(). It's rather if we made this string translatable, then it should have been extracted and we will grab its value if it has been translated.

So how do we know ACF-JSON files (or fields) are translatable and needs to be extracted to build a catalog? That's where metadata are needed which indicate whether or not something is translatable, and what is the source language.

Source language can be made easy: same as PHP code.
But what JSON element is translatable is more complex.
For example the value for conditional_logic is probably not translatable, but the one for placeholder could be.

Several possibilities exist to define which keys to translate and which not to, see https://zanata.atlassian.net/browse/ZNTA-667
which point to many formalization attempts (but not based on PO/gettext)
https://developer.chrome.com/extensions/i18n
http://okapiframework.org/wiki/index.php?title=JSON_Filter
https://webtranslateit.com/fr/docs/file_formats/json
https://docs.transifex.com/formats/json/

For a, more simple,gettext()-based solution, I don't know of a mainstream extractor, but it could be straightforward.

Example 1:

Eg, adding a key at the end of a field-group file (but UI would be needed to configure these keys):

    "_i18n": {
        "language": "es_US", # default
        "policy": "whitelist", # default
	"include": ["label","instructions","display_format","*place*"],  # include "placeholder"
	"exclude": ["label_placement"]
    }

PO JSON extractor's job is just to recursively look at every key to see whether it may be translated and create a PO file like:

#: acf-json/group_5ae987ca1c9ee.json: fields > layouts > 5a18f826f42eb > sub_fields[0] > label
msgid "Fooo"
msgstr "Bar"

It could hold below 100 LoC within a standalone executable PHP script, bundled with ACF, that can be referenced in Poedit.

Example 2:

For Google Chrome extension inspired solution (see above link):
We writing JSON files, prefix translatable keys with __MSG_.

• Extractor would be made even more simple
• Conditional call to __() can make field loading more efficient
• ACF UI would have to be modified to let user enable/disable i18n on the individual field level rather than a simple list of regexp.
• Less backward-compatible (older ACF version wouldn't know __MSG_ is a special key prefix)

The advantage of this kind of solutions are that they work on the file-format level (JSON) without entering into the detail of ACF-specific structuration (list of fields, expected keys, ...)

ping wp-cli/i18n-command/issues/52 / @swissspidy and @aduth (WordPress/gutenberg@c539390) since they may provide some input?

[elliotcondon]

Hi @drzraf

Thanks for the reply and awesome info!
I'm 100% focused on Gutenberg this week, so I won't be able to offer much in reply, but I've added this to my to-do and hope to look into this shortly.

[DhrRob]

Is there any update on this?

[elliotcondon]

Hi @DhrRob - No update on this issue as of yet. Apologies, but we must remain focused on the larger priorities right now such as Gutenberg compatibility and REST API updates.