Plone UI Text Style Guide

[mpalomaki]

plone_ui_text_style_guide_v1_2_4.md

Plone UI Text Style Guide

Responsible Persons

Proposer

Mack Palomäki

Seconder

Rob Gietema
Mikel Larreategi @erral

---

Abstract

This PLIP proposes the adoption of the first formal style guide for UI text authoring in the Plone ecosystem: the Plone UI Text Style Guide. The guide establishes standards for English canonical source text — the foundation from which all translations derive.

The core principle is straightforward: all user-facing strings should be translatable. This means UI text quality and translation-readiness are not separate concerns — they are the same concern. Rules that make text translatable (consistent capitalization, unambiguous phrasing, proper placeholder formatting) are identical to rules that make text good.

The guide documents:

1. Canonical source text rules — capitalization, punctuation, terminology, placeholder syntax
2. File format standards — the role of #. Default: comments, .pot/.po structure, extraction workflows
3. Architectural context — how Plone's gettext extension works, the two-world (backend/frontend) reality
4. Governance — ownership, tooling requirements, release cycle separation

This proposal does not introduce new technology or change existing architecture. It documents and stabilizes existing conventions that have evolved organically without formal specification.

---

Motivation

1. The Plone ecosystem has no formal UI text standards

After 20+ years, Plone has never documented how developers should write user-facing strings. Conventions exist but are transmitted through tribal knowledge, code review osmosis, and inconsistent practice.

2. Current i18n conventions are fragmented and undocumented

Analysis of current .pot files (December 2025) reveals four incompatible conventions:

Component	Format	Documented
GNU gettext (standard)	msgid is source text	Yes (GNU)
Plone backend	#. Default: comment	No
Volto	#. Default: comment	No
Volto Slate	# defaultMessage:	No

Plone core itself has only 43% coverage of the #. Default: convention it pioneered.

3. Quality suffers without standards

Current canonical English strings contain:

• Inconsistent capitalization (Title Case vs sentence case)
• Spelling variations (British vs American English)
• Terminology drift ("Log in" vs "Sign in" vs "Login")
• Ambiguous single-word strings that translate incorrectly across languages

4. AI-assisted translation requires predictable structure

Modern translation workflows — whether using AI, CAT tools, or translation management systems — depend on consistent source text. Unpredictable formatting creates parser complexity and quality failures.

5. Onboarding friction

New contributors have no reference documentation. The learning curve for "how to write UI text in Plone" is unnecessarily steep.

---

Assumptions

1. English remains the canonical source language. This guide does not propose changing Plone's use of English as the source language for UI strings.

2. Existing architecture is preserved. The guide documents current conventions; it does not propose replacing gettext, React Intl, or introducing new runtime systems.

3. Adoption is incremental. Legacy code is not required to retrofit immediately. New code MUST comply; existing code SHOULD migrate over time.

4. Tooling follows standards. The guide defines what tools should enforce, not how they should be implemented. Tooling development is a separate effort.

5. Translation quality is translator-controlled. This guide covers source text only. Translation correctness remains the responsibility of language teams.

---

Proposal & Implementation

Phase 1: Style Guide Adoption (This PLIP)

1. Publish the style guide as an official Plone documentation resource
2. Establish the canonical source text rules (Section 5 of the guide) as the standard for all new code
3. Document the architectural context so developers understand why conventions exist, not just what they are
4. Define governance — the i18n team maintains the guide; significant changes require PLIPs

Phase 2: Tooling Development (Future PLIPs)

The guide identifies tooling requirements but does not mandate implementations:

Tool	Purpose	Status
Linter	Validate source text against rules E1–E18	To be developed
Pre-commit hooks	Catch violations before commit	To be developed
CI integration	Block PRs with style violations	To be developed
Migration scripts	Audit and convert non-conforming packages	To be developed

Phase 3: Core Compliance (Future Work)

Systematic audit and correction of Plone core packages to achieve full compliance. This is significant work (estimated 2,000+ string corrections in plone domain alone) and should be planned separately.

Key Standards Introduced

Canonical Source Text Rules (MUST for new code):

Rule	Description
E1	Sentence case for all UI text
E2	No terminal periods on labels
E6	Single spaces, no leading/trailing whitespace
E8	American English spelling
E11	Named placeholders with semantic names (${username} not ${0})
E15	Consistent hyphenation and compound words
E16	Curly quotes for UI references, straight quotes for technical values

File Format Standards:

• All packages MUST use #. Default: for canonical English text
• .pot files are templates; msgstr MUST be empty
• .po files contain translations; msgstr is translator-controlled
• Corrections to #. Default: require source code changes (not .po edits)

---

Deliverables

Deliverable	Location	Status
Plone UI Text Style Guide v1.x	plone/documentation or dedicated repo	Draft complete
Quick Reference Card	Appendix to guide	Draft complete
Message Categorization Guide	Appendix E	Draft complete
Quotes and Apostrophes Reference	Appendix F	Draft complete
How to Read navigation	Guide introduction	Draft complete

Documentation integration:

• Link from Plone 6 documentation "Contributing" section
• Link from Volto documentation "i18n" section
• Reference in cookieplone templates

---

Risks

Risk	Impact	Mitigation
Adoption resistance	Developers ignore standards	Start with documentation, add tooling gradually; make compliance easy
Legacy code burden	Retrofitting is expensive	Phase approach: new code MUST comply, legacy SHOULD migrate over time
False sense of completion	Guide published but not enforced	Tooling development roadmap; CI integration as goal
Scope creep	Guide expands beyond UI text	Explicit non-goals section; content translation (plone.app.multilingual) remains out of scope
Maintenance burden	Guide becomes outdated	Clear ownership (i18n team); version history; PLIP process for changes

What will NOT break:

• Existing installations continue to work unchanged
• No runtime changes to translation lookup
• No database migrations required
• No breaking API changes

Training/documentation impact:

• Positive: developers finally have a reference
• Effort: existing contributors learn new standards (modest)

---

Participants

Role	Person	Responsibility
Proposer / Author	Mack Palomäki	Guide authorship, PLIP shepherding
Seconder	Rob Gietema	Review, Volto/Nick alignment
i18n Team	TBD	Long-term maintenance
Review	Plone community	Feedback during PLIP process

[erral]

• It would be quite easy to convert volto-slate messages to have #. Default instead on #. defaultMessage, we already did that in Volto

• For those backend messages that have n #. Default, it would be easy to change i18ndude to create such default message from the msgid (keep them both aligned). I don't think it would create any error when recreating the POT files and updating the PO files again, but I would need to double-check that.

• For style violations, plone.meta already includes codespell checks, perhaps we could enhance those checks with the ones defined here.

• Validity of PO files: we already have a check in plone.app.locales that compiles the PO file to MO to check the validity and it is enforced on Pull Requests.

[davisagli]

Thanks for your effort to document and standardize our approach in this area!

In general this looks good to me, and I like the phased plan that proceeds incrementally.

In terms of integrating the UI Text Style Guide into the Plone documentation:

• I'd strongly recommend that it ends up in the https://github.com/plone/documentation/ repository (assuming @stevepiercy agrees) to facilitate cross-linking with other documentation.
• I think more work is needed than simply adding links to the new guide. In particular at least these chapters have overlapping material and would probably need to be updated, replaced, or cross-linked:
  • https://6.docs.plone.org/i18n-l10n/translating-text-strings.html
  • https://6.docs.plone.org/i18n-l10n/contributing-translations.html
  • https://6.docs.plone.org/i18n-l10n/resync-translations.html
  • https://6.docs.plone.org/volto/development/i18n.html
  • https://6.docs.plone.org/volto/development/add-ons/i18n.html

[stevepiercy]

I'm in favor of moving forward with this PLIP.

For the technical implementation, I think that @mpalomaki has already had conversations with many people, including at Plone Conference and at least one sprint. I don't know if it's been run through the gauntlet of the Steering Circle, Volto Team, or Classic UI Team, but I think their agreement would be critical to move forward.

Documentation would reflect the plan of the technical implementation.

• All documentation source files live at https://github.com/plone/documentation/ and version control. This will then be published under https://6.docs.plone.org/.
• Discuss with @stevepiercy and @erral and probably other primary stakeholders how to structure and organize the new documentation following the guidance of the Diátaxis framework.
• Revise or merge content from existing i18n and l10n documentation listed by @davisagli with the new guide.

[mpalomaki]

plone_ui_text_style_guide_v1_2_5.md

Added: Section 5.11 Ordinal Numbers (rules E19–E22) — covers cross-language ordinal formation models, Intl.PluralRules with type: 'ordinal', per-language callback design, period as universal fallback, .pot comment requirements. Documents rrule RecurrenceWidget upstream limitation. Updated: Quick Reference Card, Appendix B. Motivated by Polyglot project analysis of 67 languages revealing structural incompatibilities with English-centric ordinal formatting.

It has been suggested the style guide is divided into sections that cleanly separate background/tutorial content and rules/instructions.

I am also creating additional tooling that will accompany the style guide in the coming months. Drafts for style conventions for all 67 non-English languages are also available so if there any ideas / interest in how to incorporate this, let me know.

[tisto]

+1 from me. Thank you @mpalomaki for your efforts on that matter!