Namespacing official Apostrophe module localizations

[abea]

Apostrophe 3 core has the localization strings namespaced with apostrophe:. This allows other modules to use localization strings with the same keys without conflicts. Read more: https://v3.docs.apostrophecms.org/guide/localization/static.html#using-namespaces

The question: Should we use that same namespace for all official Apostrophe modules (those created and supported by the core maintainers)? Or do we need unique namespaces for each module (e.g., apos-form: for the form module).

If we do use the same namespace each module would need to be a bundle that includes a sub-module that improves @apostrophecms/i18n. That makes sense for the form module, for example, which is already a bundle. If the module was something like Apostrophe Redirect, which isn't a bundle, that is a bit of a different story. That said, it's not a lot of complication to add that bundled module in, and the value of a single namespace seems high to me.

My recommendation would be that we do use a single namespace for official module localization strings for the sake of consistency and simplicity in naming. Thoughts?

[abea]

Two more things worth noting:

There is nothing stopping non-official modules from doing the same thing. Anyone could create a module that improves @apostrophecms/i18n and then they use the apostrophe: namespace. We certainly discourage that since it increases the potential for l10n key conflicts. I'm not sure what else there is to say about that.

The other thing is that the more we use the same namespace the more we have to be careful about creating conflicts. If the core team creates 20-30 modules over time that could become a lot to watch out for. We would probably end up doing some kind of module-level unofficial namespacing, such as apostrophe:form for the form module strings (e.g., apostrophe:formSubmitButton). Does this defeat the benefit of the single namespace? I'm not sure.

[boutell]

To clarify the technical points:

Modules that ship phrases, even as part of the apostrophe namespace, do not need to improve @apostrophecms/i18n at all. Any module can contain phrases in any namespace, all it has to do is configure its i18n module and specify ns. If three modules all contribute to one namespace they merge in configuration order.

So there is nothing preventing @apostrophecms/redirect from shipping phrases with no bundle, whether it contributes to the apostrophe namespace or not.

Given that we can do it either way though, there's still a lotta ins, a lotta outs...

• Eventually we must ship these phrases in other languages.
• The default English phrases at least are likely to ship with the modules that use them.
• If that's so, we don't want to fork the non-English phrases off into some other place, such as apostrophe core, which would force a weird schedule where apostrophe core must be updated every time other modules we ship are updated.
• We could ship the fr phrases in an @apostrophecms/l10n-fr module that developers install if they want it. That would solve the problem of updating apostrophe core on a weird schedule just because phrases for some other module got updated. But this would only work well if we use a single namespace, since we don't want to force @apostrophecms/l10n-fr to be a bundle contributing to a zillion namespaces.
• We could also ship the localized phrases for each module with each module. That seems like it could be a lot for translators. However it makes intuitive sense for the people installing and maintaining modules, and I think that has to govern. All of the stuff for module X is in module X, the end.

So here's what I would recommend:

• All modules ship with their own phrases in their own namespace. In the case of bundles, there is one namespace for the bundle.
• The namespace naming pattern should be what Bea is already using: apos_form, apos_redirect, etc. Based directly on the name of the module (or bundle).
• Translations for the core module get PR'd into the core module's i18n folder, where en.json is now.
• Translations for other modules get PR'd into those modules' i18n folders, where their en.json files are now.
• At some point in the future, we think about making an aggressively simple web app where invited translators can contribute phrases without having to worry about all this. That tool would know about all of our modules on the back end and just let translators translate, and it would help us update the .json files in the repos quickly. We had something like this in A1.5 and it was much appreciated and led to pretty rapid translation. But, for time reasons this is in the future. We might also use paid translation services that already provide interfaces like this.

[abea]

I hadn't understood the cascading string localization. That's good to know.

Translations for other modules get PR'd into those modules' i18n/i18n folders, where their en.json files are now.

The nesting has me confused there. You mean the module's i18n folder? It wouldn't have i18n/i18n unless it's a bundle (with a name change) or core.

I think I'm on board with that recommendation. It does seem best to keep module strings with the module code. I could see installable locales being useful, but it would turn translation into a bit of a scavenger hunt.

Your suggestion to not use the single namespace is to avoid worrying about conflicts? That makes sense. I realize I initiated apos_form in the in-progress form module, but the snake case style isn't used elsewhere, so we should probably go camel case.

[boutell]

i18n/i18n was a mistake on my part, good catch. Just the i18n folder of the module concerned.

I would say separate namespaces because of conflicts mainly, yes. The same key can mean two things to two developers.

A gray area is the intentional reuse of existing apostrophe: phrases by other modules, alongside new phrases in their own namespace. I think this is something we should not try to forbid, in that (1) we can't prevent it, (2) it helps standardize language for things that really are conceptually the same, and (3) removing those phrases from core is a bc break for translators anyway (assuming they are still used, at least).

[boutell]

(I do think some minor "bc breaks" to localization phrases are going to happen occasionally and we probably can't be as strict about this as we are about, say, changing a documented method's first argument.)

[abea]

I think we've landed on a plan to namespace individually installed modules with unique strings. So only Apostrophe core uses apostrophe:. Redirect would use aposRedirect (going with camel case) and SEO aposSeo. When we get to porting something like apostrophe-security-headers, we should probably start abbreviating to aposSecHead or something like that.

• All of this only applies to official modules.
• Any community modules should use their own unique and usable namespaces (or a best effort to be unique) to avoid conflicts.
• Using an apos namespace likely can't be prevented, but is highly discouraged. They are all in Apostrophe projects, so there is no general value in using that prefix.
• Project code should not need to namespace locale strings at all. If a project does need namespacing for locale strings then they should probably aim to be unique as well (e.g., a short version of the organization name).

[boutell]

Looks good to me!

…

On Thu, Sep 30, 2021 at 11:46 AM Alex Bea ***@***.***> wrote: I think we've landed on a plan to namespace individually installed modules with unique strings. So only Apostrophe core uses apostrophe:. Redirect would use aposRedirect (going with camel case) and SEO aposSeo. When we get to porting something like apostrophe-security-headers, we should probably start abbreviating to aposSecHead or something like that. - All of this only applies to official modules. - Any community modules should use their own unique and usable namespaces (or a best effort to be unique) to avoid conflicts. - Using an apos namespace likely can't be prevented, but is highly discouraged. They are all in Apostrophe projects, so there is no general value in using that prefix. - Project code should not need to namespace locale strings at all. If a project does need namespacing for locale strings then they should probably aim to be unique as well (e.g., a short version of the organization name). — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#3454 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAH27MUKHNPJTJUGZC2DQTUESA5BANCNFSM5E5UH3XA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

-- THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER APOSTROPHECMS | apostrophecms.com | he/him/his