Skip to content

Transifex Integration

IntraVox participates in Nextcloud's central Transifex translation pool from v1.6.0 onwards. This document describes the translation workflow, the file conventions, and why discovered ≠ enabled: admins curate which translated languages actually appear in their intranet.

Required files

These files configure the Transifex sync. They are present in the IntraVox repo:

File Purpose
.tx/config Transifex resource configuration (PO format, points the sync bot at translationfiles/<lang>/intravox.po).
translationfiles/templates/intravox.pot English source template — what translators see on Transifex.
.l10nignore Excludes paths (node_modules/, docs/, demo-data/, screenshots, etc.) from the Nextcloud l10n sync bot.

Translation flow

Translator on Transifex
    │
    │ (1) translates strings
    ▼
Transifex resource (o:nextcloud:p:nextcloud:r:intravox)
    │
    │ (2) NC l10n sync bot pulls translations
    ▼
GitHub PR
    │  l10n/<lang>.json + l10n/<lang>.js (regenerated by scripts/generate-l10n.js)
    │
    │ (3) merged into IntraVox repo
    ▼
Next IntraVox release
    │
    │ (4) tarball includes new language files
    ▼
Admin's Nextcloud instance
    │
    │ (5) Admin sees the new language in the "Available languages" section
    │     of the Demo Data tab in admin settings, can tick it to enable.
    ▼
End users in that locale see IntraVox content menus once admin enables.

Two distinct language sets

A pre-1.6.0 install had a single hardcoded list ['nl','en','de','fr'] baked into 12 services. From 1.6.0 there are two distinct sets, both managed by OCA\IntraVox\Service\LanguageService:

1. Discovered languages

Every language IntraVox ships a translation for, derived from a filesystem scan of l10n/*.json. Grows automatically as Transifex delivers new translations — no code change required.

$languageService->getDiscoveredLanguages();
// → ['de', 'en', 'fr', 'nl'] (pre-Transifex)
// → ['de', 'en', 'es', 'fi', 'fr', 'it', 'ja', 'nl', ...] (post-Transifex)

2. Enabled languages

The subset the admin has explicitly activated for use in IntraVox menus, navigation, and content folders. Stored as a JSON array in oc_appconfig.intravox.enabled_languages.

$languageService->getEnabledLanguages();
// Default (legacy fallback for upgrades): ['de', 'en', 'fr', 'nl']
// After admin disables DE+FR:             ['en', 'nl']

English is non-removable. It is the guaranteed fallback for every code path; the service forces it into the enabled set even if the admin tries to remove it.

Why discovered ≠ enabled — admin curation prevents menu pollution

Transifex's community translations can grow to 30+ languages quickly. Without admin curation, every IntraVox install would show language menus full of locales the organisation does not use. That is a UX failure (visual noise) and a content-management failure (each language is a separate content folder with its own pages, navigation, and footer).

The 1.6.0 design splits the responsibility cleanly:

  • The dev team (and the Transifex translator community) decide which languages get a translation.
  • The Nextcloud admin decides which translated languages get a place in their intranet.

A new Transifex language landing in l10n/ appears in the admin UI's "Available languages" section but stays inactive until the admin ticks it. That tick triggers an empty homepage creation; the language is then ready for content.

Demo content only for NL+EN

IntraVox ships full-intranet bundled demo content under demo-data/{nl,en}/. For all other enabled languages, the "Install" action creates only an empty homepage. This is intentional: maintaining full demo content (~46-73 page files per language) across 30+ Transifex languages would balloon the package size and the demo-content quality would degrade since none of it is translator-reviewed.

Bundled LANGUAGE_META in DemoDataService declares the per-language flags:

private const LANGUAGE_META = [
    'nl' => ['name' => 'Nederlands', 'flag' => '🇳🇱', 'full' => true],
    'en' => ['name' => 'English',    'flag' => '🇬🇧', 'full' => true],
    'de' => ['name' => 'Deutsch',    'flag' => '🇩🇪', 'full' => false],
    'fr' => ['name' => 'Français',   'flag' => '🇫🇷', 'full' => false],
];

Future Transifex-shipped languages without an entry fall back to ['name' => $code, 'flag' => '', 'full' => false].

Upgrade-safety contract

These seven rules govern every change in 1.6.0. Every PR touching the language code must respect them:

  1. No language folder is ever deleted automatically — not on toggle-off, not on upgrade, not by cleanup.
  2. Default for installs upgrading from <1.6.0 is ['nl','en','de','fr'] — exactly the previous hardcoded set.
  3. SetupService upgrade migrations skip language folders that don't already exist. occ upgrade from 1.5.x to 1.6.0 creates zero new folders.
  4. English cannot be disabled — fallback for every code path.
  5. License page-counts stay per-language; toggling does not reset counts.
  6. LanguageService::setEnabledLanguages() calls PageService::invalidateAllCaches() after writing the config — disabled languages can never serve stale cache entries.
  7. occ upgrade from 1.5.x to 1.6.0 produces zero user-visible changes until the admin acts.

Local translation workflow

Developers updating translations during development:

# After editing l10n/<lang>.json (manual or via Transifex pull):
npm run l10n   # regenerates l10n/<lang>.js from <lang>.json
npm run build

The Node script scripts/generate-l10n.js converts the Nextcloud .json format to the OC.L10N.register(...) .js format that the webpack bundle consumes at runtime.

Adding a new language

  1. Via Transifex (the only path for community-shipped translations): a translator contributes on Transifex → the Nextcloud sync-bot opens a PR with l10n/<lang>.json + l10n/<lang>.js → IntraVox merges and ships the new translation in the next release.
  2. In an install: the language appears automatically in the admin UI's "Available languages" section after upgrade. The admin ticks it to enable; an empty homepage is created on first activation.

Requesting the Transifex resource

The o:nextcloud:p:nextcloud:r:intravox resource must be provisioned by the Nextcloud team. Open a GitHub issue on nextcloud/docker-ci with the pot template URL, repo URL, and a copy of .tx/config. Until the resource exists, the bot has nothing to sync — translations are maintained manually for the four bundled languages.

See also