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

2 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:

1 Like