Multi-Language Support¶
Since v1.7.0, IntroVox is auto-translated into every language Nextcloud supports via the nextcloud/introvox Transifex resource. Admins do not opt languages in or out; they only manage overrides — optional custom copy that replaces the default for a specific language.
How language coverage works¶
The runtime model in one paragraph:
Every NC user gets the wizard in their Nextcloud language. IntroVox tries the user's full language first (
pt_BR), then its base language (pt), then English. Default copy is auto-translated via$l->t()against the Transifex translation pool. An admin can optionally save awizard_steps_<lang>override; overrides are made per base language, so an override forptalso serves users withpt_BRorpt_PT. An override replaces the defaults for that language only.
There is no list of "supported languages" inside IntroVox. The list is whatever Transifex has translated, plus English (always). IntroVox 2.0.0 ships 105 languages as they stood on Transifex on release day, also languages with less than 25% of the strings translated; what is not translated yet shows in English. A translation made on Transifex after a release reaches users with the next IntroVox release.
Language detection at runtime¶
ApiController::getWizardSteps() calls IFactory::findLanguage(null) (deliberately not findLanguage('introvox')) to get the user's raw language preference without NC silently rerouting to a language IntroVox happens to ship a file for. Steps:
- Read user lang via
IFactory::findLanguage(null)— e.g.pt_BR - Make the candidates: the full language, then its base language:
pt_BR,pt - Look up
wizard_steps_pt_BR, thenwizard_steps_ptinoc_appconfig - An override exists → serve the first one found (after group-visibility filtering)
- No override → take the first candidate IntroVox has a translation for (
IFactory::languageExists()):pt_BR, elsept, else English (not the system default).DefaultStepsService::getForLanguage()then serves the eight default steps in that language viaIFactory::get('introvox', <lang>)
Before 2.0.0 only the base language was used, so a translation for pt_BR or zh_CN never reached anyone.
Fallback table¶
| User language | Admin override exists? | What the user sees |
|---|---|---|
nl |
yes | The admin's wizard_steps_nl content as-is |
nl_BE |
yes, for nl |
The nl override: overrides are per base language |
nl |
no | Auto-translated defaults from Transifex (or English if no Dutch translation) |
pt_BR |
no | The pt_BR translation; without one the base language pt, else English |
pt_BR |
yes, for pt |
The pt override: an override goes before any translated defaults |
it |
no, no Italian translation | English defaults (explicit en fallback) |
xx (invalid) |
n/a | English defaults |
The explicit English fallback prevents the surprising "Italian user gets Dutch tour" behaviour caused by NC's default findLanguage() validation.
All of the above is about the welcome tour. A tour for an app has no Transifex defaults: it only has the steps an admin wrote. A user gets them in their own language, else in the base language, else in the tour's main language. The built-in tours are the exception: as long as none of these languages has steps of the admin's own, users get the built-in steps, translated into their own language, or in English while a translation is missing. See Tours.
Adding a language override (admin)¶
Per-language overrides live in the database, not on Transifex. They are per-install custom copy that an admin authors directly.
- Go to Settings → Administration → IntroVox → Tours and click Edit steps on the Welcome tour
- Click Add language override
- Search the full Nextcloud language list, pick a language, click Add override
- The editor shows the default steps in that language (in English while there is no translation) as a starting point. Edit them; the override row is written with the first change you save
To discard an override and return to the auto-translated defaults: select the language → click Reset → confirm.
See Language Management for the full workflow.
Translation flow on Transifex¶
For default tour copy (the welcome tour's eight default steps, the steps of the built-in tours, and all admin/personal-settings UI strings):
- We commit
translationfiles/templates/introvox.potto GitHub - The Nextcloud Transifex sync bot pushes the POT to Transifex (resource:
nextcloud/introvox) - Community translators contribute on Transifex
- The same bot opens PRs to commit
l10n/<lang>.json+l10n/<lang>.jsback to the repo - The next IntroVox release ships the new translations; end users in that language pick them up automatically
For per-install admin overrides: Transifex is not involved. Each override is custom copy authored by the admin for their installation only.
Transifex infrastructure¶
The repo carries:
.tx/config— Transifex resource configuration (PO format, source = English)translationfiles/templates/introvox.pot— POT template extracted from all$l->t()andt('introvox', ...)callsl10n/.gitkeep— keeps the directory tracked even when empty.l10nignore— exclusions for the sync botscripts/po2l10n.py— Python helper that converts the PO files pulled from Transifex (translationfiles/<lang>/introvox.po) intol10n/<lang>.jsonandl10n/<lang>.js, as the sync bot does
The sync was requested in docker-ci#938 and went live alongside v1.7.0.
Default-step strings as Transifex msgids¶
Since v1.6.0, the welcome tour's eight default steps go through t('introvox', '<English source>') (in DefaultStepsService::build()). The English source text is the Transifex msgid, so translators see real sentences instead of opaque step_welcome_title-style keys.
Existing customised step content (stored in oc_appconfig.wizard_steps_<lang>) is independent and unaffected by Transifex updates.
Display names for the override picker¶
The Add language override picker shows native language names (e.g., "Nederlands", "Português") via OCP\L10N\IFactory::getLanguages(). Every language Nextcloud knows about is selectable, once per base language (en_GB is merged with en) — not only those that already have an IntroVox translation. An admin can therefore author an override for a language that Transifex hasn't covered yet; their override wins until a Transifex translation arrives, at which point Reset hands the language back to the defaults.
Upgrade notes (1.6.x → 1.7.0)¶
Versions before 1.7.0 auto-persisted the default tour content into oc_appconfig the first time the admin opened the Steps tab. After upgrade these byte-identical defaults are now treated as overrides (and visible in the override-dropdown). They keep working but stop receiving Transifex translation updates for those languages until the admin clicks Reset. See Language Management.
See Also¶
- Language Management — full admin override workflow + upgrade notes
- Transifex Integration — sync-bot workflow
- API Reference — language-aware endpoints