Standard i18n/translation support for plugin UI and template strings

[ahliweb]

Problem

EmDash currently has no translation infrastructure for plugins or templates. The only i18n in the system is:

Component	I18n Support	Mechanism
Admin UI	✅	Lingui + .po catalogs in packages/admin/src/locales/
Content data	✅	Row-per-locale model in DB
Plugins	❌	No .po files, no translation API, no i18n hooks
Templates	❌	UI strings hardcoded in English in .astro files

Concrete impact

Plugins — A plugin that adds a settings page, dashboard widget, or custom block type has no way to present translated UI. All strings are hardcoded English:

// Today: every plugin hardcodes English
<Button>Save Settings</Button>  // ← No translation mechanism available

Templates — Starter templates (blog, portfolio, marketing) render labels like "Read more", "Published on", "Next post" in English only. There's no mechanism for site builders to translate template strings.

What plugins currently have access to

• ctx.site.locale — read-only, always available
• content.locale — per-content-item locale field
• ContentListWhere.locale — query filter

But there's no way to serve translated plugin UI strings based on this locale.

Proposed discussion points

1. Should plugins ship their own .po catalogs? Or should the admin UI catalog absorb plugin strings?
2. Should the Lingui macro system be available in plugin code? Or a lighter alternative (e.g. a PluginContext.translate(key, locale) API)?
3. Template i18n — Should EmDash provide an Astro i18n utility? Or is template i18n better left to the Astro ecosystem?
4. Locale resolution — Plugins would need to resolve the user/admin locale, not just the site locale. Currently only ctx.site.locale is exposed.
5. Registry considerations — If plugins ship translation catalogs, how are they published and versioned in the registry?

Related

• Discussion i18n: Translatable site title, tagline, collection names, etc. #403 — i18n for site title/tagline/collection names (related but different scope)
• PR i18n(id): complete Indonesian translation (7 strings) #1162 — Latest Indonesian translation — demonstrates the admin translation process works well, but plugins and templates are excluded

@ascorbic — would appreciate your thoughts on whether this is on the roadmap or if there is a preferred approach.

[ascorbic]

I would like to discuss how plugins might be able to ship translations, both for native and sandboxed plugins. I think there a few possible ways, but I'd be open to ideas. For templates, I think we should stick to Astro's i18n, but we could see about whether we should include it in the default templates

[ahliweb]

Since opening this discussion, I've implemented the plugin-owned translation approach in our AWCMS-Micro fork. It's working well with both native and sandboxed plugin boundaries. Here's what we built:

---

1. Manifest-based i18n catalog

Each plugin ships its own translation catalog inline in the manifest:

// runtime.ts
export const AWCMS_EXAMPLE_MANIFEST = {
  id: "awcms-micro-example",
  i18n: {
    defaultLocale: "en",
    supportedLocales: ["en", "id"],
    messages: {
      en: {
        "awcms.nav.group.dashboard": "Dashboard",
        "awcms.nav.overview": "Overview",
        "awcms.nav.access": "Access Control",
      },
      id: {
        "awcms.nav.group.dashboard": "Dasbor",
        "awcms.nav.overview": "Ikhtisar",
        "awcms.nav.access": "Kontrol Akses",
      }
    }
  }
};

2. resolveLabel — pure JS fallback chain

// resolve-label.ts
export function resolveLabel(
  labelKey: string,
  fallbackLabel: string,
  messages: TranslationMessages | undefined,
  requestedLocale: string,
  defaultLocale = "en"
): string {
  if (messages?.[requestedLocale]?.[labelKey])
    return messages[requestedLocale][labelKey];
  if (messages?.[defaultLocale]?.[labelKey])
    return messages[defaultLocale][labelKey];
  return fallbackLabel || labelKey;
}

Fallback order: requested locale → default locale → fallbackLabel → labelKey

3. Navigation items: labelKey + fallbackLabel

Every nav item carries both a translation key and an English fallback — nothing breaks if a locale is missing:

{
  id: "overview",
  labelKey: "awcms.nav.overview",
  fallbackLabel: "Overview",
  path: "/overview",
}

4. PluginLocalNav component

<PluginLocalNav
  groups={normalizedGroups}
  currentPath={currentPath}
  locale={locale}
  messages={manifest.i18n?.messages}
  defaultLocale="en"
/>

5. Lingui integration in admin pages

const { i18n } = useLingui();
const locale = i18n.locale;

<PluginLocalNav
  locale={locale}
  messages={AWCMS_EXAMPLE_MANIFEST.i18n?.messages}
/>

---

What works

Aspect	Result
Decoupling	Plugin translations ship with the plugin — no core catalog changes needed
Sandbox-compatible	resolveLabel is pure JS — works in native React pages and sandboxed routes
Multi-locale	English + Indonesian shipped; adding a third is just one more key in messages
No Lingui in sandbox	Sandboxed plugins use plain resolveLabel; native plugins can use Lingui macros

What we'd do differently

• Larger plugins might benefit from shipping .json files instead of inline messages objects. The resolveLabel API stays the same.
• We considered a ctx.translate(key) API for sandboxed routes but haven't needed it — the manifest pattern covers all our use cases.

Templates

We stuck with Astro's i18n for templates. EmDash starter templates can follow Astro's routing + i18n patterns without needing a separate template translation layer.

---

TL;DR

Plugins should own their translation catalogs entirely. EmDash only needs to provide:

1. The locale resolution context (which locale is active)
2. A small lookup utility (resolveLabel)

Everything else — catalog format, key naming, supported locales — stays with the plugin author.

[ascorbic]

I don't think the manifest would be the right place for it. It should be .po files, probably compiled during publish.

[ahliweb]

@ascorbic Thanks, that makes sense. I’ll revise my previous plan and move to .po files compiled during publish instead. I’ll implement it first in the standalone plugin project as a concrete example, then align the broader approach with that pattern.

[ahliweb]

As a follow-up, I have now written down the .po-based direction as a concrete working standard in the standalone plugin project: https://github.com/ahliweb/awcms-micro/blob/main/awcmsmicro-dev/docs/awcms-micro/i18n-po-translation-standard.md

The intent there is to keep it aligned with EmDashs existing translation model and with the guidance in this discussion:

• plugin and template translations live inside their own package boundaries
• .po catalogs are the source of truth, with English as the source locale
• catalogs should be compiled during publish/build rather than stored as inline manifest translation objects
• native admin UI can use Lingui directly, while sandboxed or non-React surfaces can consume compiled catalog output through a small adapter

A few concrete examples from that standard, so the idea is understandable without opening the doc:

• plugin catalogs live inside the plugin package, for example packages/plugins/<plugin-id>/src/locales/en/messages.po and packages/plugins/<plugin-id>/src/locales/id/messages.po
• template catalogs follow the same pattern inside the template package, for example templates/<template-id>/src/locales/en/messages.po
• PO entries keep English in msgid and place the translation in msgstr, for example msgid "Save settings" / msgstr "Simpan pengaturan"
• placeholders and tags stay unchanged across translations, for example msgid "Authentication error: {error}" must keep {error} intact in msgstr
• plugin UI surfaces like sidebar labels, settings pages, dialogs, toast messages, validation text, and accessibility labels should all flow through the PO-backed path

Im using that standard first in the standalone plugin work as an implementation example, so the approach can be tested in practice before proposing anything broader upstream.

[ahliweb]

@ascorbic One follow-up question: would you be open to this same .po-based approach being added or adapted for EmDashs built-in plugins and starter templates as well?

Im asking because if the standalone plugin example proves out cleanly, it seems like it could also provide a consistent direction for first-party plugin UI strings and template copy, while still keeping templates aligned with Astro i18n where appropriate.

[ascorbic]

Yes any approach should be used for built-in plugins too

[ahliweb]

@ascorbic As a next step, would you be open to a PR proposal that aligns plugin and template i18n with the .po-based direction discussed here?

I would scope it as two related but separable tracks.

Plugin i18n

For plugins, I would avoid manifest-inline translation objects and use plugin-owned .po catalogs compiled during build or publish.

The concrete work would be:

1. Define a standard plugin catalog layout, for example:
   • packages/plugins/<plugin-id>/src/locales/en/messages.po
   • packages/plugins/<plugin-id>/src/locales/id/messages.po
   • compiled output generated during build or publish
2. Add package or publish tooling so plugin catalogs are compiled and included with the plugin artifact.
3. Expose the active admin locale to plugin UI surfaces.
4. Provide a small runtime adapter or helper for resolving plugin messages from compiled catalogs.
5. Support both native admin plugin UI and sandboxed plugin boundaries.
6. Move first-party plugin UI strings away from hardcoded English.

The first-party plugin surfaces I would expect to cover are:

• plugin admin page titles and navigation labels
• settings page labels, descriptions, validation messages, empty states, and buttons
• dashboard widget titles and body copy
• block or field UI labels exposed by plugins
• toast messages, dialog text, confirmation copy, and error text
• accessibility strings such as aria-label, title, and placeholder text

For sandboxed plugins, the important part is that the runtime should not require Lingui macros to execute inside the sandbox. Native React admin pages can use Lingui directly, but sandboxed or non-React surfaces should be able to consume compiled catalog output through a small adapter.

Built-in template i18n

For templates, I agree with the earlier direction that they should stay aligned with Astro i18n rather than inventing a separate EmDash-only template translation layer.

The concrete work would be:

1. Decide which first-party templates should be i18n-aware by default.
2. Add Astro i18n configuration to those templates.
3. Remove hardcoded lang="en" from layouts and derive it from the active locale.
4. Move public template strings into template-owned .po catalogs or an Astro-compatible translation layer.
5. Route template copy through that translation path, for example:
   • navigation labels
   • Read more
   • Published on
   • Next post / Previous post
   • search, filter, and empty-state text
   • footer and metadata copy
6. Review seed/menu/taxonomy defaults only where they are actually user-visible template copy.
7. Keep content localization separate from UI/template string localization.

Existing reference implementation

I have already been testing this direction in ahliweb/awcms-micro, which is also based on EmDash and has started implementing .po catalogs for plugin and template strings:

https://github.com/ahliweb/awcms-micro

The more specific standard I wrote down there is:

https://github.com/ahliweb/awcms-micro/blob/main/awcmsmicro-dev/docs/awcms-micro/i18n-po-translation-standard.md

That implementation is useful as a proof-of-concept because it keeps translations inside the plugin/template package boundary, uses English msgid values as the source, preserves placeholders/tags across translations, and compiles catalogs instead of storing inline manifest messages.

Suggested PR strategy

I would keep the upstream work atomic:

1. First PR: document and implement the plugin .po catalog pipeline and runtime lookup helper.
2. Second PR: migrate one small built-in plugin as the reference implementation.
3. Third PR: apply the same pattern to the rest of the first-party plugin UI.
4. Separate template PR: add Astro i18n support to one starter template first, then expand if the pattern works well.

That should make the direction reviewable without coupling plugin i18n, template i18n, and all first-party migrations into one large change.

[pitscher]

Looking forward to this! Let me know if you need a helping hand. :)