Vertalingen¶

Elke voor de gebruiker zichtbare tekenreeks die een plug-in toont moet vertaalbaar zijn, met catalogi voor alle vijftien ondersteunde talen — en, pl, de, fr, es, pt_PT, pt_BR, nl, sv, nb, da, fi, it, cs, sk — voordat de plug-in als klaar geldt. Dat is dezelfde lat als bij tests.

Catalogi¶

Elke plug-in die enige tekenreeks heeft draagt per taal één .ts-catalogus in haar map Translations/:

Translations/
  MyPlugin_en.ts
  MyPlugin_pl.ts
  MyPlugin_de.ts
  MyPlugin_fr.ts

Koppel ze aan de bouw via mte_add_plugin:

mte_add_plugin(NAME MyPlugin
    SOURCES Src/MyPlugin.cpp
    TRANSLATIONS
        Translations/MyPlugin_en.ts
        Translations/MyPlugin_pl.ts
        Translations/MyPlugin_de.ts
        Translations/MyPlugin_fr.ts
)

De bouw draait lrelease om de .qm-bestanden klaar te zetten; TranslationManager laadt ze tijdens het draaien op catalogusnaam (plug-incatalogi onder Plugins/Translations/<Plugin>/).

Tekenreeksen voor vertaling merken¶

Geef de voorkeur aan QObject::tr(...) (context = de klasse) voor gewone interfaceteksten.
Het hulpje tr_() omhult QCoreApplication::translate("<Context>", s) voor tekenreeksen buiten een QObject.

tr_() is onzichtbaar voor lupdate

lupdate kan de context binnen tr_() niet oplossen, dus die catalogi worden met de hand onderhouden. Houd de tekst van <source> byte voor byte gelijk aan de tekenreeks tijdens het draaien, anders wordt de vertaling stilzwijgend niet toegepast.

Een taalwissel volgen terwijl een pagina open staat¶

De gebruiker kan de taal van de interface wijzigen in Voorkeuren ▸ Algemeen zonder te herstarten. Qt stuurt dan een QEvent::LanguageChange naar elke widget — maar een widgetboom waarvan de teksten één keer gezet zijn, in de code die hem opbouwde, houdt de oude taal totdat het venster gesloten en heropend wordt.

PluginApi/Qt/Retranslator.h handelt dat af zonder dat u elke tekenreeks twee keer hoeft te schrijven. Hij legt vast hoe elke tekenreeks gemaakt werd en speelt de opname af wanneer de taal verandert:

#include <PluginApi/Qt/Retranslator.h>

QWidget* MyPage::createWidget(QWidget* parent)
{
    auto* page = new QWidget(parent);
    auto& rt   = MTE::plugin::Retranslator::installOn(page);

    m_watch = new QCheckBox(page);
    rt.add([this] { m_watch->setText(tr_("Watch open files")); });

    m_size = new QSpinBox(page);
    rt.row(form, m_size, [] { return tr_("Font size:"); });   // QFormLayout caption

    return page;
}

add() voert zijn lambda meteen uit, zodat de plek van de aanroep precies leest als de regel «zet de tekst» die hij vervangt, en elke tekenreeks toch één keer in uw broncode staat.
row() doet hetzelfde voor het bijschrift van een QFormLayout, dat anders onbereikbaar wordt zodra addRow() het verwerkt heeft.
installOn() is per widget idempotent; de recorder is een kind van die widget en sterft ermee. Kan uw pagina een widget overleven die u vastgelegd hebt, houd die dan in een QPointer.

Net als PluginApi/Qt/ISettingsPage.h is dit een optionele Qt-header: voeg hem alleen in vanuit code die al QWidgets bouwt (hij heeft Qt6::Widgets nodig). Het Qt-vrije deel van PluginApi wordt er niet door geraakt.

Wat niet vertaald wordt¶

Twee dingen blijven met opzet in de taal waarin hun auteur ze schreef:

De name en description van uw plug-in uit plugin.json, zoals getoond in Voorkeuren ▸ Plug-ins. Het manifest wordt gelezen voordat de plug-in geladen wordt — dat is wat de pagina in staat stelt plug-ins op te sommen die uitgeschakeld zijn of tegen een andere API-versie gebouwd zijn — dus er is op dat moment geen catalogus om ze in op te zoeken.
De labels van een declaratieve (Python-)instellingenpagina of een declaratief dokpaneel. Dat zijn gegevens die uw worker naar de host stuurt, geen tekenreeksen die de host tegen een catalogus kan oplossen.

Alles wat een plug-in tijdens het draaien registreert — opdrachttitels, menu-items, doktitels, bijschriften van instellingenpagina's — wordt op de gewone manier vertaald die hierboven beschreven staat.

Drie van die tekenreeksen zoekt de host op, niet uw code, en wel in de gedeelde context PluginMenus: elk segment van een menuPath, elke title van een opdracht en de category van de opdracht. Lever alle drie mee als <source>-vermeldingen in de context PluginMenus van uw eigen catalogi. De categorie is wat de gebruiker leest in de kolom Categorie van Voorkeuren ▸ Sneltoetsen; ontbreekt ze in de catalogus, dan toont de kolom het ruwe Engelse woord naast de vertaalde kernregels. Een categorie die ook een menutitel is (Search, Encoding) deelt één vermelding: houd daarin de &-mnemoniek voor het menu, de host haalt hem weg voor de kolom.

Definitie van «klaar»¶

De lokalisatie van een plug-in is pas klaar wanneer alle vijftien .ts-bestanden bestaan, gekoppeld zijn, en lrelease 0 onafgemaakte tekenreeksen meldt.