Plone/Volto Internationalization Style Guide — Seeking Community Feedback

Documentation
1

Hello everyone,

I set out to write a short style guide/document summarizing Plone's i18n conventions for my own reference. What I discovered is that twenty years of outstanding community effort cannot be written in a short summary, hence it has expanded somewhat more than intended.

Background

I've been working on automated AI-assisted translations for the Plone ecosystem as part of a project I'm calling the "Polyglot Translation Monster Machine." To build effective tooling, I needed to understand the existing conventions deeply — and found that while the practices are well-established, the documentation is scattered across blog posts, tribal knowledge, and source code comments.

What this is (and isn't)

I want to be clear: nothing is broken in Plone's i18n infrastructure. The extraction tools work. The translation pipelines work. Maurits van Rees' workflows have kept things running smoothly for years. This style guide is not a critique — it's an attempt to document what already exists, fill gaps where conventions are implicit rather than explicit, and provide a reference for those who need to understand the system in detail.

Current status

I have used this guide as the foundation for translating Nick CMS and Volto to 30 languages with 100% string coverage. I'm currently working through Plone core and will be uploading these translations for community review shortly after additional QA.

The document

The style guide is available for download in the link below.

Since the document covers the entire Plone/Volto/Nick ecosystem, I'm uncertain which repository it ultimately belongs in. Guidance on this would be appreciated.

Why I'm posting

As a relative newcomer to this community, I'm presenting this draft style guide with appropriate humility. There are certainly errors, and I'm hoping to receive feedback before formally finalizing it and submitting this as a PLIP and proposing it for the official documentation.

I would be grateful for:

  • Corrections where I've misunderstood the architecture or history

  • Guidance on community preferences

  • Advice on the appropriate repository for this document (I have signed the contributors agreement)

  • Feedback on whether this level of detail is useful or excessive

  • Any thoughts on the proposed conventions themselves

Thank you in advance for your time and guidance.

Mack

3 Likes
2

Any changes to documentation should be submitted as a pull request to GitHub - plone/documentation: Plone Documentation .

To set it up, see Set up, build, and check the quality of documentation — Plone Documentation v6 .

Within that part of the documentation, there are many more tips, tricks, and guidance.

3

The style guide spans Plone and Volto (+Nick) - submit to both? Core?

4

Nick is not yet part of Plone core.

When submitting documentation PRs to multiple repos, including documentation, volto, plone.api, and plone.restapi, it’s easiest to follow the documentation setup guide than have multiple projects open.

5

Will Nick make "Plone backend" (the python/zope part) unnecessary?

6

It’s an option.

If you don’t want the Node.js stack, or you want to continue to use Volto with the Python/Zope backend, then Python and Zope are necessary.

If you want to use only a Node.js stack, specifically Nick with Volto, then you won’t need the Python/Zope backend.

Check out:

7

About this:

Package Total Strings Has #. Default msgid-only Coverage
Plone 3,569 1,533 2,036 43%
Volto 990 990 0 100%
Volto Slate 32 0* 32 0%*
Nick CMS 260 260 0 100%
widgets 147 0 147 0%

The 2,036 I think are mostly unused strings or strings without the Default attribute but with a valid sentence (not an id), correct? Or maybe there are lot of languages that are not updated anymore?

8

They are not unused messages. Look at these, they are msgid-only, without the Default, and are not unused messages:

2 Likes
9

So it should be doable to update them using the msgid as Default. Or are there corner cases? A CI script can check if Default are missing? And, finally, is this really important? I mean, if the msgid contains the plain english text, Default is not useful and you've to keep both, Default and msgid, in sync, correct?

10

The default message is extracted also from the templates and python code, so not only we need to run a script o identify where it is missing, we need to fix all the templates and python code to have it.

11

Oh, now I got it. Any chance to have a list of templates and python code where this happen? Or, is there an open issue that describe the problem? I can volunteer some time to edit and fix, if it is something that can be done. I'm doing it for the weblate italian translation (nice system!), I think I can do it on templates and python code, at least in the simplest cases.

12

Hi Yuri

I am using my own psql database and AI to update everything - but lets be clear - Plone is not broken - I started this work for my own use but i am happy to share my findings and results, if there is interest. My project requires many languages so that is my motovation. I need a style guide for translation automation. I will upload full translations for all official EU languages as soon i have finished additional quality checks. In my system I can producee updated .pot and .po files but it is a bit early for that. In some cases source code needs fixing too so it is a much bigger task. Fow now, if it ain’t broken - don’t fix it. What I have attempted is to document some things which have happened (and why) and propsed some rules for the sake of cosistency. Be aware the I am new to the community and I have limited knowledge of the vast treasure that Plone is. If you wish to discuss, feel free to contact me.

Kind regards,

Mack

2 Likes