Taalbestanden in Joomla

1. De basis

1.1 Twee betekenissen van "taal"

Laten we eerst de twee begrippen uit elkaar houden die binnen Joomla hetzelfde woord gebruiken:

In dit artikel behandelen we alleen de eerste kolom.

1.2 Taal is een extensietype

Een taal is één van Joomla's extensietypen. Een taal wordt geïnstalleerd, ingeschakeld, bijgewerkt en verwijderd net zoals elke andere extensie. Het enige verschil is dat een taalpakket uit .ini-bestanden bestaat in plaats van PHP-logica:

1.3 De taalcode

Elke taal heeft een unieke taalcode in de vorm xx-XX: een kleine ISO-639-taalcode, gevolgd door een koppelteken en een hoofdletterige ISO-3166-regiocode.

en-GB   Engels (Verenigd Koninkrijk)   ← de brontaal van Joomla
en-US   Engels (Verenigde Staten)
nl-NL   Nederlands (Nederland)
nl-BE   Nederlands (België)
de-DE   Duits (Duitsland)
ar-AA   Arabisch                       ← van rechts naar links

De code en-GB heeft een bijzondere rol. Joomla is oorspronkelijk geschreven in deze taal en gebruikt deze als universele fallback. Als een vertaling ontbreekt in nl-NL, toont Joomla automatisch de tekst uit en-GB.

1.4 Waar de bestanden staan

Net als bij templates bestaan er twee aparte mappenstructuren, één voor elke client (front-end en back-end):

public_html/
├── language/                     ← SITE (front-end) talen
│   ├── en-GB/
│   ├── nl-NL/
│   └── overrides/                ← jouw eigen taaloverrides
└── administrator/
    └── language/                 ← ADMINISTRATOR (back-end) talen
        ├── en-GB/
        ├── nl-NL/
        └── overrides/

De front-end en back-end worden onafhankelijk van elkaar vertaald. Een bezoeker kan de website in het Nederlands zien terwijl jij de backend in het Engels gebruikt, omdat beide omgevingen verschillende taalmappen laden.

1.5 Binnenin een taalmap

Een taalmap bevat veel bestanden. Er is één .ini-bestand per extensie, aangevuld met enkele speciale bestanden:

language/en-GB/
├── joomla.ini             ← gedeelde en algemene teksten (het "woordenboek" van Joomla)
├── lib_joomla.ini         ← teksten van de frameworkbibliotheek
├── com_content.ini        ← één bestand per component ...
├── com_content.sys.ini    ← ... plus het systeemtaalbestand (zie deel 3)
├── mod_articles_latest.ini
├── plg_system_...ini
├── langmetadata.xml       ← manifest (taalcode, locale, rtl, kalender)
├── localise.php           ← taalregels (meervouden, transliteratie)
└── index.html

Eén .ini-bestand per extensie houdt alles overzichtelijk en modulair. Joomla laadt alleen de bestanden die voor de huidige pagina nodig zijn.

3. .ini versus .sys.ini

Elke extensie bevat twee taalbestanden en niet slechts één. Dit detail verrast bijna iedereen de eerste keer.

com_content.sys.ini  (klein, altijd snel te laden)
└── COM_CONTENT="Artikelen"
└── COM_CONTENT_XML_DESCRIPTION="De artikelencomponent ..."

com_content.ini      (groot, alleen geladen wanneer de component rendert)
└── COM_CONTENT_SAVE, COM_CONTENT_N_ITEMS_ARCHIVED, ... (honderden sleutels)

Vuistregel: als een tekst zichtbaar moet zijn voordat de extensie wordt uitgevoerd, bijvoorbeeld in het installatiescherm, de extensielijst of de keuze van een menutype, dan hoort deze thuis in .sys.ini. Alle andere teksten horen in het gewone .ini-bestand.

5. Anatomie van een taalpakket

Een volledig taalpakket, bijvoorbeeld nl-NL, is zelf een installeerbare extensie. Naast de gebruikelijke .ini-bestanden bevat het drie speciale onderdelen.

5.1 langmetadata.xml, het manifest

Dit bestand (vóór Joomla 4 bekend als xx-XX.xml) beschrijft de taal voor het volledige systeem:

<metafile client="site">
    <name>Engels (en-GB)</name>
    <version>6.1.0</version>
    <metadata>
        <tag>en-GB</tag>
        <rtl>0</rtl>                       <!-- 1 = van rechts naar links -->
        <locale>en_GB.utf8, en_GB, english</locale>
        <firstDay>0</firstDay>             <!-- 0 = zondag -->
        <weekEnd>0,6</weekEnd>
        <calendar>gregorian</calendar>
    </metadata>
</metafile>

Dit bestand bepaalt de locale voor PHP-datum- en nummerfuncties, de rechts-naar-links-instelling die templates gebruiken en de eerste dag van de week in kalenderweergaven.

5.2 localise.php, taalspecifieke regels

Sommige logica past niet in een eenvoudig .ini-bestand. Regels voor meervouden verschillen per taal, daarom kan elk taalpakket een kleine PHP-klasse bevatten:

abstract class En_GBLocalise
{
    // Welke meervoudsvorm hoort bij een bepaald aantal?
    public static function getPluralSuffixes($count)
    {
        return $count == 1 ? ['1'] : ['MORE'];
    }

    // (sommige talen definiëren ook transliterate(), zoekwoordregels, ...)
}

Engels kent twee meervoudsvormen, Pools drie en Arabisch zelfs zes. De methode getPluralSuffixes() bepaalt hoe Text::plural() (zie deel 7) de juiste vertaalsleutel kiest.

5.3 De map overrides/

Elke client heeft een map overrides/ met daarin één bestand, xx-XX.override.ini, dat altijd voorrang krijgt op alle andere taalbestanden. Dit is de gebruiksvriendelijke overridefunctie die in deel 10 wordt behandeld:

language/overrides/en-GB.override.ini
administrator/language/overrides/en-GB.override.ini

Wanneer dezelfde sleutel zowel in een normaal taalbestand als in een overridebestand voorkomt, gebruikt Joomla altijd de waarde uit het overridebestand.

7. Placeholders en meervouden

7.1 Text::sprintf(), waarden invoegen

Het .ini-bestand bevat de placeholders en de code levert de daadwerkelijke waarden aan:

COM_CONTENT_N_ITEMS_ARCHIVED="%d artikelen gearchiveerd."

echo Text::sprintf('COM_CONTENT_N_ITEMS_ARCHIVED', $count);
// $count = 5  ->  "5 artikelen gearchiveerd."

Doordat het getal niet hardcoded in de tekst staat, kunnen vertalers de woordvolgorde aanpassen aan hun eigen taal. Dat is essentieel voor talen waarin het werkwoord of het getal op een andere plaats in de zin staat.

7.2 Text::plural(), grammaticaal correcte aantallen

"1 artikel" versus "5 artikelen" is niet zomaar een eenvoudige if-constructie. Joomla bouwt de sleutel op uit een basissleutel plus een meervoudsachtervoegsel, terwijl localise.php bepaalt welk achtervoegsel gebruikt moet worden:

COM_CONTENT_N_ITEMS_ARCHIVED="%d artikelen gearchiveerd."   ; standaard / MORE-vorm
COM_CONTENT_N_ITEMS_ARCHIVED_1="Artikel gearchiveerd."      ; enkelvoud

echo Text::plural('COM_CONTENT_N_ITEMS_ARCHIVED', $n);

// $n = 1  -> sleutel ..._1     -> "Artikel gearchiveerd."
// $n = 7  -> sleutel ..._MORE  -> "7 artikelen gearchiveerd."

De verwerking verloopt als volgt:

Text::plural('..._ARCHIVED', $n)
        |
        v
getPluralSuffixes($n)  ->  ['1']  of  ['MORE']
        |
        v
probeer ..._ARCHIVED_1  /  ..._ARCHIVED_MORE
(val terug op ..._ARCHIVED indien nodig)

Dit is één van de belangrijkste redenen waarom een taal meer is dan alleen een woordenlijst. Grammatica is logica, en die logica zit in localise.php.

9. Laden en laadvolgorde

9.1 Het meeste laden gebeurt automatisch

Wanneer de dispatcher bijvoorbeeld com_content uitvoert, laadt Joomla automatisch com_content.ini voor de actieve taal en client. Handmatig laden is zelden nodig, maar het kan wel:

$lang = $this->getLanguage();              // of Factory::getApplication()->getLanguage()
$lang->load('com_content', JPATH_ADMINISTRATOR);   // laad expliciet de taalstrings van een andere extensie

9.2 De cascade, laatst geladen wint

Vertalingen worden samengevoegd tot één grote opzoektabel terwijl bestanden worden geladen. Een latere definitie overschrijft altijd een eerdere:

1. joomla.ini / lib_joomla.ini   (algemeen woordenboek)
2. com_xxx.ini                   (de component)
3. template- en modulestrings
4. en-GB.override.ini            (OVERRIDES - altijd als laatste, winnen altijd)
        |
        v
één samengevoegde KEY -> waarde-opzoektabel voor dit verzoek

Omdat overrides als laatste worden geladen, hebben ze altijd voorrang op teksten uit de core of extensies. Dat maakt de overridefunctie uit deel 10 zowel veilig als krachtig.

9.3 Fallback naar en-GB

Wanneer een vertaling ontbreekt, geeft Joomla niet direct op:

Zoek 'COM_X_FOO' in nl-NL
   |
bestaat in nl-NL.ini?  -- ja -> gebruik deze waarde
   | nee
bestaat in en-GB.ini?  -- ja -> gebruik Engels (veilige fallback)
   | nee
toon de SLEUTEL letterlijk  (teken dat deze nergens bestaat)

Dankzij deze fallback blijft een website bruikbaar, zelfs wanneer een vertaling nog niet volledig is afgerond.

11. Het algemene woordenboek

11.1 joomla.ini, gedeelde teksten voor iedereen

Algemene, herbruikbare teksten staan centraal in joomla.ini, zodat elke extensie ze kan gebruiken en een override direct overal effect heeft:

ERROR="Fout"
WARNING="Waarschuwing"
JYES="Ja"
JNO="Nee"
JALL="Alles"
JGLOBAL_TITLE="Titel"
JACTION_CREATE="Aanmaken"
JACTION_DELETE="Verwijderen"

Het voorvoegsel J geeft aan dat het om een algemene Joomla-tekst gaat. Gebruik daarom liever JGLOBAL_TITLE dan een nieuwe sleutel zoals COM_MYTHING_TITLE te verzinnen. Die vertaling bestaat immers al in elk taalpakket.

11.2 Ook datum- en getalnotaties zijn vertaalbaar

Het bestand joomla.ini bepaalt niet alleen woorden, maar ook hoe datums worden weergegeven, via PHP-date()-patronen:

DATE_FORMAT_LC  = "l, d F Y"      ; maandag, 01 juni 2026
DATE_FORMAT_LC2 = "l, d F Y H:i"  ; ... 14:30
DATE_FORMAT_LC4 = "Y-m-d"         ; 2026-06-01

Vertalers kunnen zowel de namen van maanden en dagen als de volgorde van datumonderdelen aanpassen. Daardoor worden datums vanzelf op een natuurlijke manier weergegeven in elke taal, zonder codewijzigingen.

13. Taal en de database

13.1 De grote verrassing, vertalingen staan niet in de database

Dit verrast veel beheerders. Joomla bewaart vertalingen volledig in bestanden. Er bestaat geen vertaaltabel. De .ini-bestanden op schijf zijn de vertaalgegevens. De database houdt alleen bij welke talen bestaan en welke taalpakketten geïnstalleerd zijn:

TEKSTEN (de woorden)        -> .ini-bestanden op schijf           (NIET in de database)
WELKE TALEN BESTAAN         -> #__languages                       (enkele records)
"taal is geïnstalleerd"     -> #__extensions                      (type='language')
OVERRIDES                   -> overrides/xx-XX.override.ini       (NIET in de database)

13.2 De drie tabellen die wel meedoen

SELECT extension_id, element, client_id, enabled
FROM   #__extensions
WHERE  type = 'language';        -- alle geïnstalleerde taalpakketten, site + administrator

SELECT lang_code, title, sef, published
FROM   #__languages;             -- alle talen die de website kent

13.3 Waarom er geen override-tabel bestaat

De tool Language Overrides uit deel 10 wijzigt teksten, maar schrijft niets naar de database. In plaats daarvan wordt er toegevoegd aan overrides/en-GB.override.ini op schijf:

System → Language Overrides   --schrijft naar-->   language/overrides/en-GB.override.ini
                                                    (een gewoon .ini-bestand, als laatste geladen -> wint altijd)

Omdat overrides gewone bestanden zijn, kun je ze eenvoudig back-uppen, vergelijken in Git en samen met de rest van de website uitrollen. Ze blijven bovendien bestaan, zelfs wanneer je een databasebackup terugzet. :contentReference[oaicite:0]{index=0}

15. Ontwikkelen en best practices

15.1 Vertalingen toevoegen aan je eigen extensie

Voor ontwikkelaars bestaat het proces uit drie stappen:

1. Gebruik voor elke tekst een sleutel, nooit een letterlijke tekst: echo Text::_('COM_EXAMPLE_HEADING');
2. Definieer de sleutel in language/en-GB/com_example.ini van je extensie (en gebruik .sys.ini voor naam- en menuteksten).
3. Lever deze bestanden mee binnen de extensie (zie deel 4.3), zodat updates automatisch ook nieuwe vertalingen bevatten.

; com_example.ini
COM_EXAMPLE_HEADING="Welkom"
COM_EXAMPLE_N_RESULTS="%d resultaten gevonden"
COM_EXAMPLE_N_RESULTS_1="Eén resultaat gevonden"

15.2 Sleutels goed benoemen

• Gebruik een extensieprefix: COM_EXAMPLE_..., MOD_EXAMPLE_..., PLG_SYSTEM_EXAMPLE_.... Zo voorkom je naamconflicten in de gedeelde vertaaltabel.
• Beschrijf de betekenis, niet de tekstwaarde: gebruik COM_EXAMPLE_SAVE_SUCCESS in plaats van COM_EXAMPLE_GREEN_MESSAGE.
• Herbruik bestaande globale sleutels zoals JYES, JGLOBAL_TITLE en JACTION_* in plaats van ze opnieuw aan te maken.
• Houd sleutels stabiel. Het hernoemen van een sleutel verbreekt alle bestaande vertalingen ervan.

15.3 Waar horen taalbestanden van een extensie thuis?

Dit is een veelgestelde vraag. Het korte antwoord: binnen de extensie zelf. Plaats ze in de eigen map language/ van de extensie. De centrale map /language/ is vooral een overblijfsel uit oudere versies en een nooduitgang voor websitebeheerders, niet de plek waar jij als ontwikkelaar je taalbestanden neerzet.

com_example/
├── com_example.xml
├── language/en-GB/com_example.ini  + .sys.ini      ← siteteksten
└── admin/language/en-GB/com_example.ini + .sys.ini ← backendteksten

De nuance is dat de centrale taalmap nog steeds voorrang krijgt wanneer daar een bestand met dezelfde naam aanwezig is. Dat is bewust zo ontworpen, zodat een websitebeheerder teksten kan overschrijven zonder jouw extensie aan te passen. In de praktijk is de tool Language Overrides hiervoor echter veel geschikter. Dus: jij als ontwikkelaar levert taalbestanden mee binnen de extensie, terwijl een websitebeheerder tekstaanpassingen doet via Language Overrides.

17. In het kort

VERTALEN      echo Text::_('KEY')
WAARDE INVOEGEN  echo Text::sprintf('KEY', $count)
AANTALLEN     echo Text::plural('KEY', $n)   (+ key_1, key_MORE)
JAVASCRIPT    Text::script('KEY')  ->  Joomla.Text._('KEY')
XML-VELD      label="KEY" description="KEY"   (geen PHP nodig)
NAAM/MENU     plaats vroege teksten in .sys.ini
ALGEMEEN      hergebruik JYES, JGLOBAL_TITLE, JACTION_*
OVERRIDE      System -> Language Overrides (schrijft naar overrides/xx-XX.override.ini)
SLEUTEL VINDEN Global Configuration -> System -> Debug Language
TAAL INSTALLEREN System -> Install -> Languages
FALLBACK      ontbreekt nl-NL? -> en-GB -> ruwe KEY