Käännökset

Jokaisen käyttäjälle näkyvän merkkijonon, jonka liitännäinen näyttää, täytyy olla käännettävissä, ja luettelot kaikille viidelletoista tuetulle kielelle — en, pl, de, fr, es, pt_PT, pt_BR, nl, sv, nb, da, fi, it, cs, sk — täytyy olla olemassa ennen kuin liitännäistä pidetään valmiina. Tämä on sama vaatimustaso kuin testeillä.

Luettelot

Kukin liitännäinen, jolla on yhtään merkkijonoa, kantaa yhtä .ts-luetteloa kieltä kohti Translations/-kansiossaan:

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

Kytke ne käännökseen funktion mte_add_plugin kautta:

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
)

Käännös ajaa ohjelman lrelease valmistellakseen .qm-tiedostot; TranslationManager lataa ne luettelonimen perusteella ajon aikana (liitännäisluettelot kansiosta Plugins/Translations/<Plugin>/).

Merkkijonojen merkitseminen käännettäviksi

• Suosi funktiota QObject::tr(...) (konteksti = luokka) tavallisille käyttöliittymämerkkijonoille.
• Apuri tr_() kääri funktion QCoreApplication::translate("<Context>", s) merkkijonoille QObject-olion ulkopuolella.

tr_() on näkymätön ohjelmalle lupdate

lupdate ei voi ratkaista kontekstia funktion tr_() sisällä, joten noita luetteloita ylläpidetään käsin. Pidä <source>-teksti tavulleen samana kuin ajonaikainen merkkijono, muutoin käännös ei hiljaisesti tule voimaan.

Kielenvaihdon seuraaminen sivun ollessa auki

Käyttäjä voi vaihtaa käyttöliittymän kielen kohdassa Asetukset ▸ Yleiset ilman uudelleenkäynnistystä. Qt lähettää silloin tapahtuman QEvent::LanguageChange jokaiselle ohjausobjektille — mutta ohjausobjektipuu, jonka merkkijonot asetettiin kerran siinä koodissa, joka sen rakensi, säilyttää vanhan kielen, kunnes ikkuna suljetaan ja avataan uudelleen.

PluginApi/Qt/Retranslator.h hoitaa tuon ilman että jokaista merkkijonoa täytyy kirjoittaa kahdesti. Se tallentaa, miten kukin merkkijono tuotettiin, ja toistaa tallenteen, kun kieli muuttuu:

#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() ajaa lambdansa heti, joten kutsupaikka lukeutuu täsmälleen kuin se »aseta teksti« -rivi, jonka se korvaa, ja kukin merkkijono esiintyy yhä kerran lähdekoodissasi.
• row() tekee saman QFormLayout-otsikolle, joka on muutoin saavuttamattomissa, kun addRow() on kerran ottanut sen.
• installOn() on idempotentti ohjausobjektia kohti; tallennin on tuon ohjausobjektin lapsi ja kuolee sen mukana. Jos sivusi voi elää kaappaamasi ohjausobjektin yli, pidä sitä QPointer-oliossa.

Kuten PluginApi/Qt/ISettingsPage.h, tämä on valinnainen Qt-otsikkotiedosto: sisällytä se vain koodista, joka jo rakentaa QWidget-olioita (se tarvitsee kohteen Qt6::Widgets). PluginApi-kirjaston Qt-vapaa osa ei muutu.

Mitä ei käännetä

Kaksi asiaa pysyy suunnitellusti sillä kielellä, jolla niiden tekijä ne kirjoitti:

• Liitännäisesi name ja description tiedostosta plugin.json, sellaisina kuin ne näkyvät kohdassa Asetukset ▸ Liitännäiset. Manifesti luetaan ennen liitännäisen lataamista — juuri se antaa sivun luetella liitännäiset, jotka on poistettu käytöstä tai käännetty toista API-versiota vasten — joten siinä vaiheessa ei ole luetteloa, josta ne voitaisiin hakea.
• Kuvailevan (Python-)asetussivun tai telakkapaneelin nimiöt. Ne ovat dataa, jonka työntekijäsi lähettää isännälle, eivätkä merkkijonoja, jotka isäntä voisi ratkaista luettelosta.

Kaikki, mitä liitännäinen rekisteröi ajon aikana — komentojen otsikot, valikkokohdat, telakoiden otsikot, asetussivujen otsikot — käännetään yllä kuvatulla tavanomaisella tavalla.

Kolme näistä merkkijonoista hakee isäntä, ei sinun koodisi, yhteisestä kontekstista PluginMenus: menuPath-polun jokainen osa, jokaisen komennon title ja komennon category. Toimita kaikki kolme <source>-merkintöinä omien luetteloidesi PluginMenus-kontekstissa. Luokka on se, mitä käyttäjä lukee Asetukset ▸ Pikanäppäimet -ikkunan Luokka-sarakkeessa; jos se puuttuu luettelosta, sarake näyttää raa'an englanninkielisen sanan käännettyjen ydinrivien rinnalla. Luokka, joka on samalla valikon otsikko (Search, Encoding), jakaa yhden merkinnän: jätä siihen &-merkki valikolle, isäntä poistaa sen sarakkeesta.

Milloin se on valmis

Liitännäisen lokalisointi on valmis vasta, kun kaikki viisitoista .ts-tiedostoa ovat olemassa ja kytkettyinä ja lrelease ilmoittaa 0 keskeneräistä merkkijonoa.