Modernizing Galaxy's Internationalization (i18n) System

[itisAliRH]

Summary

Galaxy's internationalization system needs a coordinated modernization effort. The current custom localization system covers only ~35% of user-visible strings, uses patterns that will break with Vue 3 (PR #20787), and lacks tooling to measure or improve translation coverage. This discussion aims to gather community input on the approach before implementation begins.

Problem

Galaxy serves a global research community, yet its i18n system has significant gaps:

1. Low coverage: Only ~500 out of an estimated ~1,300–1,500 user-visible strings are wrapped in the localize() function. The remaining ~65% are hardcoded English.
2. Inconsistent/incorrect translations: Recent reports (26.0 has confusing translations #22407) highlight confusing translations (e.g., German "Geschichten" for "Histories"). Translations were contributed at different times by different people with no review process.
3. Vue 3 incompatibility: The localization plugin relies on Vue.filter() and Vue.mixin(), both removed in Vue 3. When PR Vue3 #20787 merges, the | localize filter and this.l() mixin pattern will break. These must be fixed before the Vue 3 PR merges to avoid UI regressions.
4. No coverage measurement: There's no way to know what percentage of strings are translated for any language, or which strings are missing.
5. No extraction tooling: Translatable strings must be manually identified and added to locale files. There are no scripts to extract them from source code.
6. Architectural limitations: No pluralization ("1 item" vs "N items"), no interpolation ("Hello, {name}"), no context/disambiguation, no lazy loading.

Current State

Architecture

Galaxy uses a custom, client-side-only dictionary-lookup system (client/src/utils/localization.js). There is no third-party i18n library. The backend has no i18n at all — all API responses and error messages are English-only.

Usage Patterns

Pattern	Example	Count	Vue 3 Safe?
Direct import	import localize from "@/utils/localization"	~431 calls	Yes
v-localize directive	<span v-localize>text</span>	~323 uses	Needs update
Mixin methods	this.l("text")	~123 calls	No — breaks
Vue filter	{{ "text" | localize }}	~5 uses	No — breaks

Supported Languages

Language	Translated Strings	Coverage (of ~344 root keys)
Spanish (es)	~292	Best
Chinese (zh)	~243	Good
German (de)	~164 (after #22417)	Moderate
French (fr)	~136	Partial (~48% false entries)
Japanese (ja)	~114	Moderate

Note: These numbers are against the current root locale file (~344 keys), which itself only represents ~25% of all user-visible strings.

Biggest Untranslated Areas

Area	Hardcoded Strings	Notes
Grid configs (components/Grid/configs/)	~145	Column headers, titles, actions — 0% localized
title="..." tooltip attributes	~113	Across 50+ components
Error/toast messages	~91	See also #18688
Upload dialog	~34	~58% coverage
Workflow Editor	~18	~51% coverage
placeholder="..." attributes	~50	Form inputs

Related Issues & PRs

Reference	Status	Description
#20787	Open (draft)	Vue 3 migration — will break filter/mixin patterns
#22417	Open	German localization fixes + adds de to supportedLanguages
#21736	Open	French translation update
#21044 / #21745	Merged	Chinese translation improvements + lint fixes
#22407	Open	Report of confusing German translations
#18688	Open	Include localization in error messages
#12822	Open	Spanish rendering overflow in multi-dataset operations
#13653	Closed	Bug in preferred language switching
#12475	Closed	i18n whitespace issues in v-localize directive

Proposed Solution

Phase 0: Fix Vue 3 Blockers (Before #20787 merges)

The Vue 3 PR should only merge when there are no breaking parts in the UI. The i18n-related breakages must be fixed first:

PR 0a — Update localization plugin for Vue 3:

• Replace Vue.filter("localize") → use app.config.globalProperties.$l or direct imports
• Replace Vue.mixin(localizeMixin) → use app.config.globalProperties.$l + app.provide("localize", ...)
• Update v-localize directive to Vue 3 directive API (mounted hook instead of bind)
• Migrate ~5 components using | localize filter to localize() calls
• Migrate ~27 files using this.l() mixin to direct imports

PR 0b — Create useLocalize() composable:

// client/src/composables/useLocalize.ts
import { inject } from "vue";
import { localize as defaultLocalize } from "@/utils/localization";

export function useLocalize() {
    const localize = inject("localize", defaultLocalize);
    return { l: localize, localize };
}

Phase 1: Build a Complete Translation Template + Coverage Tooling

The core idea: extract every translatable string from the codebase into a canonical template, then measure each language file against it.

PR 1a — String extraction script:
Create client/scripts/extract-i18n-strings.js that scans all .vue, .ts, .js files and extracts strings from:

• localize("...") / _l("...") function calls
• Text content inside v-localize elements
• | localize / | l filter expressions
• Grid config title: fields (and similar patterns)

Outputs a template.json — the "complete" set of strings that should be translated.

PR 1b — Coverage report & CI integration:

$ node client/scripts/extract-i18n-strings.js --report

Translation Coverage Report
===========================
Template: 1,342 strings

  es:  292 / 1,342  (21.8%)  — 1,050 missing
  zh:  243 / 1,342  (18.1%)  — 1,099 missing
  de:  164 / 1,342  (12.2%)  — 1,178 missing
  fr:  136 / 1,342  (10.1%)  — 1,206 missing
  ja:  114 / 1,342   (8.5%)  — 1,228 missing

Add a Makefile target (make client-i18n-report) and optionally a CI step to track coverage over time.

Phase 2: Wrap Remaining Hardcoded Strings

Incrementally wrap hardcoded strings in localize(), prioritized by impact:

1. Grid configs (~145 strings, consistent title: pattern, easy batch)
2. Error/toast messages (~91 strings, addresses Include localization in error messages #18688)
3. Workflow Editor (~18 strings, high-traffic)
4. placeholder / title / aria-label attributes (~187 strings)
5. Upload dialog, tool panel, remaining components

Each area can be a separate PR for easier review.

Phase 3: Complete Translations (LLM-Assisted + Community Review)

Translation completion would use an LLM-assisted workflow with native-speaker review:

1. Run the extraction script to identify missing strings per language
2. Use an LLM to generate initial translations for each batch of missing strings, with context from surrounding strings and Galaxy domain terminology
3. Native speakers from the community review and refine the LLM output in PRs
4. Repeat per language, per batch

This is neither pure LLM nor pure community effort — the LLM handles the bulk translation work while community reviewers ensure quality, domain accuracy, and natural phrasing. This approach is motivated by:

• The large number of missing strings (~1,000+ per language) makes pure manual translation impractical
• LLMs can produce good first drafts but need domain experts to catch Galaxy-specific terminology issues (as seen in 26.0 has confusing translations #22407 where generic translations produced confusing results)
• Community reviewers can focus on quality rather than the tedious work of translating hundreds of UI labels

Phase 4: Evaluate and Potentially Adopt a Standard i18n Library (Optional)

Once the template-based system is working, the community can evaluate whether adopting a standard library would provide enough value to justify the migration effort. The leading candidates for Vue 3:

Library	Weekly Downloads	GitHub Stars	Key Strengths	Considerations
vue-i18n v10	1.6M+	2,400+	Official Vue ecosystem, pluralization, ICU MessageFormat, useI18n() composable, rich tooling	Largest community, most battle-tested
fluent-vue	~2.3K	~264	Mozilla's Fluent syntax, smaller API, Vue 2+3 compatible	Smaller community, different syntax
i18next-vue	—	—	Leverages i18next ecosystem, framework-agnostic core	Good if multi-framework i18n is needed

vue-i18n is the most mature and widely adopted option — it's part of the Vue ecosystem with 1.6M+ weekly downloads, full Vue 3 support (v10 released), and features like pluralization, interpolation, lazy loading, and TypeScript support. However, adoption is not required for Phases 0–3 — the current localize() function works fine once Vue 3-compatible, and the template approach is library-agnostic.

This phase should only be pursued if the community agrees the benefits (pluralization, interpolation, tooling) justify the migration cost.

Goals

• No i18n-related breakage when Vue 3 merges — fix filter/mixin patterns first
• Measurable coverage — a script that reports exact percentages per language
• Complete translation template — every user-visible string extracted and cataloged
• All 5 languages above 80% coverage within 2 release cycles (using LLM + review workflow)
• CI guardrail — new PRs that add unlocalised strings get flagged (stretch goal)

Breakdown of PRs

Order	PR	Scope	Dependencies
0a	Vue 3 localization plugin update	Update plugin API, migrate filters/mixins	None — must land before #20787
0b	useLocalize() composable	New composable for Composition API	0a
1a	String extraction script	New script in client/scripts/	None
1b	Coverage report + CI	Makefile target, optional CI step	1a
2a	Wrap Grid config strings	~145 strings in 14 files	None
2b	Wrap error/toast messages	~91 strings across 50 files	None
2c	Wrap Workflow Editor strings	~18 strings in 8 files	None
2d	Wrap attribute strings	placeholder, title, aria-label	None
3a–3e	Translation completion (per language)	LLM draft + community review	1a (for template)
4	(Optional) Adopt vue-i18n	Library migration if community agrees	0a, 0b

PRs in the same phase (e.g., 2a–2d) can be worked on in parallel.

Questions for the Community

1. Vue 3 priority: Should Phase 0 (fix i18n for Vue 3) be the immediate focus, or are there other Vue 3 blockers that take priority?
2. Library adoption: Is the current custom system "good enough" once Vue 3-compatible + template-based, or should we invest in migrating to vue-i18n (or another library)?
3. Language priorities: Which languages should we focus on completing first? Are there other languages the community needs (e.g., Portuguese, Korean, Arabic/RTL)?
4. LLM-assisted translations: Is the community comfortable with LLM-generated initial drafts reviewed by native speakers? Any concerns about this workflow?
5. Backend i18n: Should we eventually internationalize backend error messages and API responses, or is client-side i18n sufficient?
6. Tool descriptions: Should tool XML descriptions and help text be translatable? This would require schema changes.

[nsoranzo]

I know very little about this, but it looks to me that leaving the decision of adopting a standard i18n library to last (Phase 4) would risk having to redo a good chunk of the Phase 1 and 2 work.
The list of candidate libraries is small and vue-i18n seems the obvious choice, so it seems just a matter of choosing to adopt it or keep using our custom system?

[bernt-matthias]

Do we know how many (number/%) people use i18n on the usegalaxy servers?