De gebruikersinterface vertalen

Pivotick schrijft zijn eigen tekst: de rail, de menu's, de zijbalk, de tabel, het draaipaneel, de geschiedenis, de toasts en elke title tooltip en aria-label daarachter. De i18n optie zet alles in uw taal.

const graph = new Pivotick(container, data, {
    i18n: { locale: 'fr' }, 
})

Tekst die u aan de bibliotheek overhandigt, wordt precies getekend zoals opgegeven en nooit opgezocht: knooppunt en rand labels, facet- en legendalabels, draainamen, railmodi, docktabbladen, acties in de bovenste balk en de rijen die u aan een contextmenu toevoegt. Vertaal deze voordat u ze doorgeeft.

Gebundelde talen

Elke build bevat volledige vertalingen van de ingebouwde gebruikersinterface:

Taal	Lokaal	Voorbeeld regionale tags
Engels (standaard)	en	en-GB, en-US
Vereenvoudigd Chinees	zh	zh-CN, zh-Hans
Frans	fr	fr-FR, fr-CA
Duits	de	de-DE, de-CH
Portugees	pt	pt-BR, pt-PT
Nederlands	nl	nl-NL, nl-BE
Japans	ja	ja-JP
Arabisch	ar	ar-EG, ar-SA
Spaans	es	es-ES, es-MX

Stel i18n.locale in om er één te selecteren. Regionale tags gebruiken dezelfde taalcatalogus while met behoud van hun eigen nummeropmaak, sortering en meervoudsregels. De Chinese catalogus gebruikt vereenvoudigde karakters; er is geen aparte traditioneel Chinese vertaling. Een locatie zonder gebundelde catalogus wordt Engels gebruikt tenzij u messages of translate opgeeft. Als u locale weglaat, blijft de bestaande Engelse standaard behouden; browsertaal wordt niet gedetecteerd.

De catalogi worden geëxporteerd als messagesEn, messagesZh, messagesFr, messagesDe, messagesPt, messagesNl, messagesJa, messagesAr, messagesEs en samen als bundledMessages, ook beschikbaar op Pivotick in browserbuilds.

De optie

Eigendom	Typ	Standaard	Beschrijving
locale	string	'en'	Een BCP 47-tag zoals 'fr', 'de-CH' of 'pt-BR'. Het kiest de meervoudsregels, hoe getallen worden geschreven en hoe lijsten worden gesorteerd. Indien opgegeven, wordt deze ook ingesteld als de lang van de wortel van de grafiek.
messages	Partial<Messages>	{}	Overschrijvingen met sleutel. Ontbrekende sleutels gebruiken de meegeleverde taal en vervolgens Engels.
translate	(key, params, fallback) => string | undefined		Een brug naar uw eigen vertaalbibliotheek, gevraagd voor elke sleutel die messages niet heeft.

De taal wordt ingesteld wanneer de grafiek wordt gebouwd. Om het te veranderen, bel graph.destroy() en bouw de grafiek opnieuw met de nieuwe opties.

Hoe een bericht wordt gevonden

Elk stuk tekst wordt in deze volgorde opgezocht en het eerste antwoord wint:

1. De eigen optie van het object, als deze er een heeft: UI.emptyState.render, UI.busyIndicator.label, UI.simplify.typeLabel, of de title en confirmLabel jij ga naar ctx.confirm(). Deze zijn specifieker dan welke catalogus dan ook.
2. messages, uw sleuteltabel.
3. translate, jouw brug.
4. De gebundelde taal, geselecteerd met locale.
5. Engels, als de taal geen gebundelde catalogus heeft.

Gedeeltelijke overschrijvingen worden ondersteund: wijzig alleen de voorwaarden die uw toepassing nodig heeft en de rest gebruikt de geselecteerde taal. Niet-ondersteunde talen schakelen zonder waarschuwing over naar Engels.

Toetsen en berichten

Elk bericht heeft een stabiele, gestippelde sleutel, genoemd naar de plaats waar het verschijnt: 'contextMenu.node.pin', 'history.menu.empty', 'sidebar.neighbors.connections'. De sleutels zijn getypt uit de Engelse catalogus, dus in TypeScript kan een verkeerd gespelde sleutel niet worden gecompileerd en uw redacteur voltooit de rest.

Een bericht kan drie vormen aannemen.

Tekst met tijdelijke aanduidingen

Een string, met {name} waar een waarde hoort:

messages: {
    'search.result.inGroup': 'dans {group}',
    'history.menu.count': '{count} sur {limit}',
}

Een getal wordt geschreven zoals de locale het schrijft voordat het erin gaat: 1,234 onder 'en', 1.234 onder 'de', 1 234 onder 'fr'. Een string wordt ingevoerd zoals geschreven.

Meervoudsvormen

Een bericht dat afhankelijk is van een telling is een object met één item per meervoudige categorie taal gebruikt. De categorie wordt door de browser gekozen uit de parameter count Intl.PluralRules, dus de regels zijn degene die CLDR definieert voor de landinstelling. other is vereist, omdat elke taal het heeft.

// English and French need two forms; French counts zero as one
'count.nodes': { one: '{count} nœud', other: '{count} nœuds' },

// Polish needs four: 1 węzeł, 3 węzły, 5 węzłów, 1,5 węzła
'count.nodes': { one: '{count} węzeł', few: '{count} węzły', many: '{count} węzłów', other: '{count} węzła' },

De categorieën zijn zero, one, two, few, many en other. Een vorm die de taal heeft niet gebruiken wordt nooit gekozen, en een ontbrekende valt terug op other.

Fallback English behoudt Engelse meervoudsregels onder elke landinstelling. Bijvoorbeeld een niet-ondersteund taal die nul als enkelvoud behandelt, krijgt nog steeds "0 knooppunten" van de Engelse fallback.

Een functie

Voor alles wat een sjabloon niet kan zeggen, kan een bericht een functie zijn van de onbewerkte parameters en de grafiek I18n:

'simplify.typeLabel': ({ count, type }, i18n) =>
    `${i18n.formatNumber(Number(count))} ${type === 'ip' ? 'adresses IP' : type}`,

Wat de vorm ook is, een bericht is tekst. Het wordt ingevoegd als tekst, nooit geparseerd als HTML, dus <b> verschijnt zoals geschreven.

PO-vertaalbestanden bewerken

De map locales/ van de repository bevat een gettext-sjabloon, pivotick.pot, en volledige zh.po, fr.po, de.po, pt.po, nl.po, ja.po, ar.po en es.po bestanden. Deze bestanden worden ook verzonden in het npm-pakket. Open een .po-bestand in Poedit of een andere UTF-8-teksteditor. Elke msgctxt is de stabiele berichtsleutel; msgid is de Engelse bron en msgstr is de vertaling. Houd {placeholders} intact. Voor meervoudige vermeldingen vertaalt u elk msgstr[n]-slot: Chinees en Japans hebben other alleen; Arabisch heeft zero, one, two, few, many en vervolgens other; Frans, Duits, Portugees, Nederlands en Spaans hebben one en vervolgens other. De runtime gebruikt Intl.PluralRules, waarbij ontbrekende categorieën terugvallen op other, in plaats van de gettext-header te evalueren als JavaScript.

Vanuit een bronafhandeling met npm ci voltooid:

# Refresh the template and merge English changes into the PO files
npm run i18n:extract

# Edit locales/*.po, finish empty entries and review any fuzzy translations

# Compile PO files into the TypeScript catalogues used by every build
npm run i18n:compile

# Check completeness, source text, placeholders, plurals and generated files
npm run i18n:check
npm run test:i18n

Commiteer de PO-bestanden, de sjabloon en de gegenereerde src/i18n/locales/*.ts-bestanden samen. Niet bewerken de gegenereerde bestanden rechtstreeks. Extractie behoudt bestaande vertalingen en vertalers opmerkingen, markeert gewijzigde Engelse tekst als fuzzy en laat nieuwe invoer leeg. Los deze op vermeldingen vóór het compileren. Verwijderde sleutels worden uit de actieve catalogus verwijderd. npm run build loopt i18n:check, dus een onvolledige vertaling of een verouderde gegenereerde catalogus mislukt bouwen. Deze opdrachten maken gebruik van bestaande knooppuntafhankelijkheden; er is geen systeem gettext-installatie nodig.

Om een andere taal te bundelen, voegt u de locale en meervoudige slottoewijzing toe aan scripts/i18n.mjs, extraheer en vertaal het nieuwe PO-bestand, compileer het en exporteer vervolgens de gegenereerde catalogus src/i18n/locales/index.ts en voeg het toe aan bundledMessages. Voor een taal die alleen voor toepassingen geldt, het doorgeven van een catalogus omdat i18n.messages nog steeds werkt zonder Pivotick te veranderen.

Een catalogus starten vanaf messagesEn

De Engelse catalogus wordt geëxporteerd als messagesEn, vanuit de ES-build en als Pivotick.messagesEn uit de browserbuilds. Het bevat elke sleutel met de Engelse tekst, en het zijn gewone gegevens, dus het kan worden uitgeschreven als het bestand waar uw vertalers van uitgaan:

import { messagesEn } from 'pivotick'

console.log(JSON.stringify(messagesEn, null, 4))

Laad het vertaalde bestand terug als messages. In TypeScript, een catalogus gedeclareerd met satisfies Messages moet elke sleutel een naam geven, dus een sleutel die in een latere release wordt toegevoegd, wordt weergegeven als een compileerfout in plaats van als een verdwaalde Engelse string:

import type { Messages } from 'pivotick'

export const messagesFr = {
    'count.nodes': { one: '{count} nœud', other: '{count} nœuds' },
    // …every other key
} satisfies Messages

Gebruik in plaats daarvan Partial<Messages> om onderweg te vertalen.

Uw eigen vertaalbibliotheek overbruggen

Als uw toepassing al via een bibliotheek vertaalt, behoudt translate één bron van waarheid en één taalschakelaar. Het wordt aangeroepen voor elke sleutel die messages niet heeft, met:

• key: de berichtsleutel, zoals 'count.nodes';
• params: de ruwe waarden, met ongeformatteerde getallen, dus het eigen meervoud en getal van uw bibliotheek regels zijn van toepassing;
• fallback: de Engelse tekst, al ingevuld.

Retourneer een string om deze te gebruiken, of undefined om de gebundelde taal en vervolgens Engels te gebruiken. Hier met i18next, waarvan de count param al zijn meervouden aanstuurt:

const graph = new Pivotick(container, data, {
    i18n: {
        locale: i18next.language,
        translate: (key, params, fallback) => {
            const found = i18next.exists(`pivotick.${key}`)
            return found ? i18next.t(`pivotick.${key}`, params) : undefined
        },
    },
})

Uw bronbestanden schrijven hun berichten vervolgens in de eigen syntaxis van uw bibliotheek ("{{count}} nœuds" in i18next), onder dezelfde toetsen.

Een translate die gooit, wordt opgevangen: de console geeft aan welke sleutel en de gebundelde taal (of Engels voor een niet-ondersteunde taal) wordt weergegeven. De haak ontvangt nog steeds Engels als zijn fallback argument, waarbij het overbruggingscontract behouden blijft. Als messages en translate beide een sleutel hebben, wint messages en wordt translate niet gevraagd.

Getallen, lijsten, sorteren en lang

locale omvat meer dan woorden. Daaronder:

• Counts worden geschreven met Intl.NumberFormat: "1.234 knooppunten" in het Engels, "1.234 Knoten" in Duits. Fallback English gebruikt ook de getalnotatie van de geselecteerde landinstelling.
• Lijsten met namen in één zin worden samengevoegd met Intl.ListFormat: "a, b en c", "a, b et c".
• Sorteer in de tabel, de lijst met buren en het draaitriagevenster gebruiken Intl.Collator, dus "Émile" wordt naast "Emma" gesorteerd, in het Zweeds staat "ä" na "z" en "item 10" komt erna "punt 9".

Wanneer je een locale declareert, krijgt het hoofdelement van de grafiek dit als lang, en dat geldt ook voor de delen de bibliotheek wordt buiten de root gemount (tooltips, vervolgkeuzelijsten, suggestielijsten). Schermlezers dan lees de interface met de juiste stem. Zonder locale is er geen lang ingesteld: die van de bibliotheek de tekst is Engels, maar uw gegevens in de grafiek zijn in de taal van uw pagina en die van de pagina eigen lang beschrijft dit het beste.

De lay-out van rechts naar links wordt niet ondersteund: er is geen dir-verwerking en de interface is gelegd van links naar rechts in elke taal.

Eén taal per grafiek

Elke grafiek heeft zijn eigen taal. Twee grafieken op één pagina kunnen twee talen gebruiken, en geen van beide beïnvloedt de ander.

Een grafiek binnen een grafiek spreekt die van zijn ouders: de subgrafiek die in een cluster is getekend, en de kleine burengrafiek in de zijbalk.

Tekst die de bibliotheek in uw gegevens schrijft, wordt één keer geschreven, in de taal van de grafiek: een geschiedenis het label van het item ("Hid 3 nodes") en de hoofdtekst waarmee een nieuwe notitie begint. De grafiek opnieuw opbouwen een andere taal laat die zoals ze waren.

In code: graph.i18n en plug-ins

graph.i18n is de taal van de grafiek, hetzelfde object waarmee de bibliotheek schrijft:

Lid	Wat het doet
locale	De gebruikte tag: de jouwe, of 'en'.
t(key, params?)	De tekst van een ingebouwd bericht, via de lookup hierboven.
formatNumber(value, options?)	Een getal in de cijfers van de landinstelling. Neemt Intl.NumberFormat opties.
formatList(items, options?)	Items samengevoegd als een zin. Neemt Intl.ListFormat opties.
compare(a, b)	Een vergelijker in de volgorde van de landinstelling, die veilig kan worden doorgegeven naar sort zoals deze is.
collator(options?)	De Intl.Collator achter compare, standaard numeriek.

Een plug-in leest hetzelfde object als ctx.i18n. De tekst die de plug-in zelf schrijft, is de plug-in moet worden vertaald, ingetoetst op ctx.i18n.locale; het formatteren van de tellingen en het sorteren ervan Lijsten tot en met ctx.i18n zorgen ervoor dat ze consistent blijven met de rest van de grafiek.

const nodeCounter = {
    name: 'node-counter',
    install(ctx) {
        const words = { fr: 'Total', de: 'Gesamt' }
        const label = words[ctx.i18n.locale.split('-')[0]] ?? 'Total'
        const count = ctx.i18n.formatNumber(ctx.graph.getNodes().length)
        // …draw `${label}: ${count}`
    },
}

Wat blijft zoals het is

• Uw gegevens. Knooppunt- en randlabels, eigenschapsnamen en waarden worden getekend zoals ze zijn. EEN eigenschapsnaam zonder een gedeclareerd label wordt in hoofdletters weergegeven vanaf de sleutel (first_seen leest "Eerst gezien"); declareer nodePropertiesMap of edgePropertiesMap als naam het in uw taal. De rij id die de eigenschappenlijsten boven uw eigen sleutels toevoegen, wordt geschreven als de sleutel ervan is.
• Ontwikkelaarstekst. Consolewaarschuwingen en gegenereerde fouten blijven in het Engels.
• Belangrijkste glyphs. ⌃ ⇧ ⌥ ⌘ worden weergegeven zoals ze zijn. Sleutelnamen zijn berichten (keys.ctrlCombo, keys.escape), dus een Duitse interface kan Strg+Z zeggen.
• Badge telt op de rand van een knooppunt (2k, 99+), die in drie tekens moet passen.