Transifex Integration¶
IntroVox participates in Nextcloud's central Transifex translation pool since v1.6.0. This document describes the translation workflow, the file conventions, and the auto-discovery mechanisms that let new languages appear without code changes.
Required Files¶
These files are in place in the IntroVox repository and configure Transifex sync:
| File | Purpose |
|---|---|
.tx/config |
Transifex resource configuration (o:nextcloud:p:nextcloud:r:introvox, PO format, translationfiles/<lang>/introvox.po) |
translationfiles/templates/introvox.pot |
The source strings (npm run pot: scripts/extract-en-json.js scans src/ and lib/, scripts/generate-pot.js writes the POT) |
l10n/.gitkeep |
Keeps the l10n/ directory tracked in git even before any translations land |
.l10nignore |
Exclusions for the Nextcloud l10n sync bot (e.g. docs/, js/, node_modules/, the test folders) |
Translation Flow¶
Translator on Transifex
│
│ (1) translates strings
▼
Transifex resource
│
│ (2) NC l10n sync bot pulls translations
▼
GitHub PR / direct commit
│ l10n/<lang>.json + l10n/<lang>.js
│
│ (3) merged into IntroVox repo
▼
Next IntroVox release
│
│ (4) tarball includes new language files
▼
Admin's Nextcloud instance
│
│ (5) Users in that NC language see the wizard auto-translated, no admin action needed
▼
End user sees the tour in their language
Since v1.7.0 there is no admin opt-in step — every translation that ships in l10n/ becomes available immediately. Admins only intervene if they want a per-language override (custom copy that replaces the auto-translated default for one specific language).
Auto-Discovery Mechanisms¶
Display Name Discovery (v1.6.0+)¶
The "Add language override" picker labels (e.g., "Nederlands", "Português") come from OCP\L10N\IFactory::getLanguages() — Nextcloud's built-in localized-language-name database. Every language Nextcloud knows about is selectable, not just the ones IntroVox already has a translation file for. This means an admin can author an override for a language that Transifex hasn't covered yet.
Before v1.6.0, IntroVox maintained a hardcoded map of language codes to display names (and emoji flags). Since v1.6.0 the map is gone — NC provides the names, correctly localised (an English admin sees "German", a German admin sees "Deutsch"). No emoji flags, matching the Nextcloud Settings convention.
Translation Resolution at Runtime¶
ApiController::getWizardSteps() uses IFactory::findLanguage(null) to obtain the user's raw language preference (deliberately not findLanguage('introvox'), which would re-route to a language IntroVox happens to ship a translation file for). DefaultStepsService::getForLanguage($lang) then builds the eight default steps via IFactory::get('introvox', $lang), with an explicit English fallback when $lang has no translation file — never the system default language.
Built-in Tours (2.0.0+)¶
The built-in tours for Files, Talk, Deck and Calendar are translated the same way. BuiltinTours::stepsIn($l) defines their steps with $l->t(), so their strings are in the POT like the welcome tour's; BuiltinTours::steps($id, $lang) builds them in the user's language, its base language, or English. For users, an admin's own steps for the user's language come first, then the Transifex translation, then the admin's steps in the tour's main language, then English (see API Reference).
English as Transifex Source (v1.6.0+)¶
Pre-v1.6.0, default step content used opaque translation keys:
This surfaced unusable msgids to Transifex translators, who had no context for what step_welcome_title should mean.
Since v1.6.0, default content uses English source strings as Transifex msgids:
Translators on Transifex now see the actual English text and translate it directly. This applies to:
- All 16 default wizard step titles and texts
- ~50 PWA install instruction strings (covering 9 OS/browser combos)
- All admin and personal settings UI strings
- The previously-Dutch-hardcoded "Begrepen" button (now
t('introvox', 'Got it'))
Existing customized step content stored in oc_appconfig.wizard_steps_<lang> is not affected by this change — only the built-in defaults use the new pattern.
PWA Install Instructions (v1.6.0+)¶
The wizard includes a PWA install step that detects the user's OS and browser and shows tailored instructions. Pre-v1.6.0, all ~40 strings in src/utils/deviceDetection.js and src/components/wizardSteps.js were hardcoded Dutch literals, displayed to non-Dutch users as-is.
Since v1.6.0, every PWA string is wrapped in t('introvox', '<English source>'). Existing Dutch translations are preserved (they're now sourced from l10n/nl.json rather than hardcoded), and other languages fall back to English until Transifex syncs translations.
Local Translation Workflow¶
For developers updating translations during development:
# Pull the translations and convert them (needs the tx CLI and a Transifex token):
./scripts/sync-translations.sh
# Or by hand:
tx pull -a --minimum-perc=1
python3 scripts/po2l10n.py # every translationfiles/*/introvox.po
python3 scripts/po2l10n.py de nl # only these languages
scripts/po2l10n.py converts translationfiles/<lang>/introvox.po into l10n/<lang>.js and l10n/<lang>.json, exactly as the Nextcloud Transifex bot writes them. The .js registers the translations in the browser through OC.L10N.register; the .json is what the server reads. Neither goes through webpack. Both are shipped in the App Store tarball.
The 2.0.0 Translations¶
2.0.0 ships a pull of its own from Transifex, made on release day (21 October 2026) with the steps above: every language with translations (105 languages), including those under 25% that the bot would leave out. What is not translated shows in English.
Reintroduced: DefaultStepsService (v1.7.0+)¶
A DefaultStepsService was originally removed in v1.6.0 because it shipped hardcoded Dutch defaults and was dead code. It was reintroduced in v1.7.0 — this time as the single source of truth for the eight built-in steps, shared between AdminController (editor view seed) and ApiController (end-user fetch). It uses IFactory::get('introvox', $lang) to render via Transifex, with explicit English fallback when the requested language has no translation file.
This is what made it possible to remove the legacy useDefault: true + empty-steps response pattern: the API now returns the full inline-translated step set in every response, so the client never has to rebuild defaults locally (which had been re-translating them through the browser-loaded Vue bundle, sometimes in the wrong language).
Adding a New Language¶
- Via Transifex (only path): contribute translations on Transifex → the NC sync bot opens a PR to commit them → the next IntroVox release ships the new translations and end users in that language immediately get the auto-translated tour. No admin action required.
- Authoring a custom override locally: an admin can add a
wizard_steps_<lang>override row through the UI for any language Nextcloud supports, even before a Transifex translation exists. The override wins until it's reset, at which point Transifex takes over.
For full admin instructions see Language Management.
See Also¶
- Multi-Language Support — user-facing description
- Language Management — admin configuration
- Frontend Architecture — how translations are loaded at runtime