Skip to content

Add internationalisation (i18n) support to the platform UI #8311

Description

@hmjvalineY

Description

Problem

The FlowFuse platform UI is English-only and has no i18n infrastructure. On current main (v3.0.0, 56b076e7):

  • frontend/src/i18n.js, frontend/src/locales/, frontend/src/directives/, and a root locales/ directory do not exist
  • No i18n or polyglot dependency in package.json
  • Approximate translatable string counts across 542 .vue files (79,189 lines): ~1,049 bare template text nodes, ~358 label/title/placeholder/header attribute strings, ~155 Alerts.emit messages, plus 19 email templates in forge/postoffice/templates/ and error strings in forge/routes/

There is also an inconsistency that non-English-speaking self-hosted teams hit immediately. Node-RED already ships 10 editor locales (de, en-US, es-ES, fr, ja, ko, pt-BR, ru, zh-CN, zh-TW), and because nr-launcher does not set lang in the generated settings.js, Node-RED falls back to the browser locale. So a user with a Chinese browser locale today gets a fully localised Node-RED editor embedded inside an entirely English platform shell.

Motivation

I run a self-hosted FlowFuse deployment for a Traditional Chinese (zh-TW) speaking team, and localising the platform shell is the remaining gap. I would like to contribute this upstream rather than maintain a private fork, so the work starts with the shared infrastructure and the en baseline rather than with my own locale.

Reference

I have reviewed PR #5692 and the docs/contribute/i18n.md contributor guide on its feature/i18n-implementation branch, and I am following the architecture defined there — the library choices, the locale directory layout, and the hierarchical key-naming convention.

The implementation will be written fresh against main rather than rebased from that branch, because the dependency landscape has moved since:

Package #5692 pinned Current Note
fastify ^4.25.2 ^5.8.5 on main major bump
fastify-i18n ^1.2.0 3.0.0 v3 is the Fastify 5 line (fastify-plugin@^5)
vue-i18n ^9.14.4 11.x two majors behind

Proposed implementation

  • Frontend: vue-i18n@^11, config at frontend/src/i18n.js, locale files at frontend/src/locales/<lang>.json
  • Backend: fastify-i18n@^3 + node-polyglot, locale files at locales/<lang>/common.json
  • Key naming: hierarchical namespaces grouping semantically related entries, per the guide above
  • Locale resolution: user preference → Accept-Language / navigator.language → en. fastify-i18n@3 already normalises Accept-Language (e.g. ja-JP → ja), so browser detection needs no custom code on the backend.
  • Both webpack entrypoints: webpack.config.js builds two separate Vue apps, main and setup. The plugin will be registered on frontend/src/setup.js as well as frontend/src/main.js, so the first-run setup flow can be translated too.

Scope

A single PR covering three parts:

  1. i18n infrastructure and the en baseline — the plumbing above, plus string extraction for an initial page set (starting with login and sign-up, as feature: Allow for i18n for first two pages #5692 did)
  2. zh-TW locale — the first non-English locale, proving the plumbing works end to end
  3. User language preference — a DB migration adding a language column to User, the API to read and write it, and the account settings UI to change it

On (3): User currently has no generic preferences mechanism — its schema is flat columns (tcs_accepted, suspended, and so on) — so a language preference requires a new column and therefore a migration. Flagging this for the area:migration label.

Testing

I will verify locally before opening the PR and report results in it:

  • npm run lint and npm run lint:colors clean against the pre-change baseline (currently 0 errors, 11 pre-existing warnings)
  • npm run build producing both main and setup entrypoints
  • npm run test:unit:forge, test:unit:frontend, and test:system
  • The migration applying cleanly on SQLite, and reverting
  • Manual verification that the UI renders in both en and zh-TW, and that the preference persists across sessions

Which customers would this be available to

Everyone - CE/Starter/Team/Enterprise

Have you provided an initial effort estimate for this issue?

I am not a FlowFuse team member

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions