Übersetzen der Benutzeroberfläche

Pivotick schreibt eigenen Text: die Leiste, die Menüs, die Seitenleiste, die Tabelle, das Pivot-Panel, den Verlauf, die Toasts und jeden title Tooltip und aria-label dahinter. Die Option i18n bringt alles in Ihre Sprache.

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

Text, den Sie an die Bibliothek übergeben, wird genau wie angegeben gezeichnet und nie nachgeschlagen: Knoten- und Kantenbeschriftungen, Facetten- und Legendenbeschriftungen, Pivotnamen, Schienenmodi, Dock-Registerkarten, Aktionen in der oberen Leiste und die Zeilen, die Sie einem Kontextmenü hinzufügen. Übersetzen Sie diese, bevor Sie sie weitergeben.

Gebündelte Sprachen

Jeder Build enthält vollständige Übersetzungen der integrierten Benutzeroberfläche:

Sprache	Gebietsschema	Beispiel für regionale Tags
Englisch (Standard)	`en`	`en-GB`, `en-US`
Vereinfachtes Chinesisch	`zh`	`zh-CN`, `zh-Hans`
Französisch	`fr`	`fr-FR`, `fr-CA`
Deutsch	`de`	`de-DE`, `de-CH`
Portugiesisch	`pt`	`pt-BR`, `pt-PT`

Stellen Sie i18n.locale ein, um eines auszuwählen. Regionale Tags verwenden denselben Sprachkatalog, behalten aber ihre eigenen Zahlenformatierungs-, Sortier- und Pluralregeln bei. Der chinesische Katalog verwendet vereinfachte Zeichen; Es gibt keine separate traditionelle chinesische Übersetzung. Ein Gebietsschema ohne gebündelten Katalog verwendet Englisch, es sei denn, Sie geben messages oder translate an. Durch das Weglassen von locale bleibt die bestehende englische Standardeinstellung erhalten; Die Browsersprache wurde nicht erkannt.

Die Kataloge werden als messagesEn, messagesZh, messagesFr, messagesDe, messagesPt und zusammen als bundledMessages exportiert und sind auch auf Pivotick in Browser-Builds verfügbar.

Die Option

Eigenschaft	Typ	Standardwert	Beschreibung
`locale`	`string`	`'en'`	Ein BCP 47-Tag wie `'fr'`, `'de-CH'` oder `'pt-BR'`. Es wählt die Pluralregeln aus, wie Zahlen geschrieben werden und wie Listen sortiert werden. Wenn angegeben, wird es auch als `lang` der Wurzel des Diagramms festgelegt.
`messages`	`Partial<Messages>`	`{}`	Überschreibungen per Schlüssel. Fehlende Schlüssel verwenden die mitgelieferte Sprache, dann Englisch.
`translate`	`(key, params, fallback) => string \| undefined`		Eine Brücke zu Ihrer eigenen Übersetzungsbibliothek, die nach jedem Schlüssel gefragt wird, den `messages` nicht hat.

Die Sprache wird beim Erstellen des Diagramms festgelegt. Um es zu ändern, rufen Sie graph.destroy() auf und erstellen Sie das Diagramm erneut mit den neuen Optionen.

So wird eine Nachricht gefunden

Jeder Text wird in dieser Reihenfolge nachgeschlagen und die erste Antwort gewinnt:

Die eigene Option des Features, wenn es eine hat: UI.emptyState.render, UI.busyIndicator.label, UI.simplify.typeLabel oder die title und confirmLabel, die Sie an ctx.confirm() übergeben. Diese sind spezifischer als jeder Katalog.
messages, Ihre Schlüsseltabelle.
translate, deine Brücke.
Die gebündelte Sprache, ausgewählt durch locale.
Englisch, wenn die Sprache keinen gebündelten Katalog hat.

Teilweise Überschreibungen werden unterstützt: Ändern Sie nur die Begriffe, die Ihre Anwendung benötigt, und für den Rest wird die ausgewählte Sprache verwendet. Nicht unterstützte Sprachen werden ohne Vorwarnung auf Englisch umgeschaltet.

Schlüssel und Nachrichten

Jede Nachricht hat einen stabilen, gepunkteten Schlüssel, der nach der Stelle benannt ist, an der sie erscheint: 'contextMenu.node.pin', 'history.menu.empty', 'sidebar.neighbors.connections'. Die Schlüssel werden aus dem englischen Katalog eingegeben, sodass in TypeScript ein falsch geschriebener Schlüssel nicht kompiliert werden kann und Ihr Editor den Rest erledigt.

Eine Nachricht kann eine von drei Formen annehmen.

Text mit Platzhaltern

Eine Zeichenfolge mit {name}, in der ein Wert steht:

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

Eine Zahl wird so geschrieben, wie das Gebietsschema sie schreibt, bevor sie eingegeben wird: 1,234 unter 'en', 1.234 unter 'de', 1 234 unter 'fr'. Eine Zeichenfolge wird wie geschrieben eingefügt.

Pluralformen

Eine Nachricht, die von einer Zählung abhängt, ist ein Objekt mit einem Eintrag pro Pluralkategorie, die die Sprache verwendet. Die Kategorie wird aus dem Parameter count durch Intl.PluralRules des Browsers ausgewählt, daher sind die Regeln diejenigen, die CLDR für das Gebietsschema definiert. other ist erforderlich, da es in jeder Sprache vorhanden ist.

// 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' },

Die Kategorien sind zero, one, two, few, many und other. Eine Form, die die Sprache nicht verwendet, wird nie ausgewählt, und eine fehlende fällt auf other zurück.

Fallback-Englisch behält die englischen Pluralregeln unter jedem Gebietsschema bei. Beispielsweise erhält eine nicht unterstützte Sprache, die Null als Singular behandelt, immer noch „0-Knoten“ aus dem englischen Fallback.

Eine Funktion

Für alles, was eine Vorlage nicht sagen kann, kann eine Nachricht eine Funktion der Rohparameter und der I18n des Diagramms sein:

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

Unabhängig von der Form ist eine Nachricht Text. Es wird als Text eingefügt und nie als HTML geparst, sodass <b> als geschrieben angezeigt wird.

Bearbeiten von PO-Übersetzungsdateien

Das locales/-Verzeichnis des Repositorys enthält eine Gettext-Vorlage pivotick.pot und vollständige zh.po-, fr.po-, de.po- und pt.po-Dateien. Diese Dateien werden auch im npm-Paket geliefert. Öffnen Sie eine .po-Datei in Poedit oder einem beliebigen UTF-8-Texteditor. Jedes msgctxt ist der stabile Nachrichtenschlüssel; msgid ist die englische Quelle und msgstr ist die Übersetzung. Halten Sie {placeholders} intakt. Für mehrere Einträge übersetzen Sie jeden msgstr[n]-Slot: Chinesisch hat nur other und Französisch, Deutsch und Portugiesisch haben one und dann other. Die Laufzeit verwendet Intl.PluralRules, wobei many auf other zurückfällt, anstatt den gettext-Header als JavaScript auszuwerten.

Aus einer Quell-Kaufabwicklung mit npm ci abgeschlossen:

# 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

Übertragen Sie die PO-Dateien, die Vorlage und die generierten src/i18n/locales/*.ts-Dateien zusammen. Bearbeiten Sie die generierten Dateien nicht direkt. Bei der Extraktion bleiben vorhandene Übersetzungen und Übersetzerkommentare erhalten, markiert geänderten englischen Text als fuzzy und lässt neue Einträge leer. Lösen Sie diese Einträge vor dem Kompilieren auf. Entfernte Schlüssel werden aus dem aktiven Katalog gelöscht. npm run build führt i18n:check aus, sodass der Build aufgrund einer unvollständigen Übersetzung oder eines veralteten generierten Katalogs fehlschlägt. Diese Befehle nutzen vorhandene Knotenabhängigkeiten; Es ist keine System-Gettext-Installation erforderlich.

To bundle another language, add its locale and plural-slot mapping to scripts/i18n.mjs, extract and translate the new PO file, compile it, then export the generated catalogue from src/i18n/locales/index.ts and add it to bundledMessages. Bei einer reinen Anwendungssprache funktioniert die Übergabe eines Katalogs als i18n.messages immer noch, ohne dass Pivotick geändert wird.

Starten eines Katalogs von `messagesEn`

Der englische Katalog wird als messagesEn aus dem ES-Build und als Pivotick.messagesEn aus den Browser-Builds exportiert. Es enthält jeden Schlüssel mit seinem englischen Text und es handelt sich um reine Daten, sodass es als die Datei ausgeschrieben werden kann, mit der Ihre Übersetzer beginnen:

import { messagesEn } from 'pivotick'

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

Laden Sie die übersetzte Datei als messages zurück. In TypeScript, a catalogue declared with satisfies Messages must name every key, so a key added in a later release shows up as a compile error rather than as a stray English string:

import type { Messages } from 'pivotick'

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

Verwenden Sie stattdessen Partial<Messages>, um unterwegs zu übersetzen.

Überbrückung Ihrer eigenen Übersetzungsbibliothek

Wenn Ihre Anwendung bereits über eine Bibliothek übersetzt wird, behält translate eine Quelle der Wahrheit und einen Sprachwechsel bei. Es wird für jeden Schlüssel aufgerufen, den messages nicht hat, mit:

key: der Nachrichtenschlüssel, z. B. 'count.nodes';
params: die Rohwerte mit unformatierten Zahlen, sodass die eigenen Plural- und Zahlenregeln Ihrer Bibliothek gelten;
fallback: der englische Text, bereits ausgefüllt.

Geben Sie eine Zeichenfolge zurück, um sie zu verwenden, oder undefined, um die gebündelte Sprache und dann Englisch zu verwenden. Hier mit i18next, dessen count-Parameter bereits seine Pluralformen steuert:

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
        },
    },
})

Ihre Ressourcendateien schreiben ihre Nachrichten dann in der Syntax Ihrer Bibliothek ("{{count}} nœuds" in i18next) unter denselben Schlüsseln.

Eine translate, die ausgelöst wird, wird abgefangen: Die Konsole sagt welche Taste und die gebündelte Sprache (oder Englisch für eine nicht unterstützte Sprache) wird angezeigt. Der Hook erhält weiterhin Englisch als fallback-Argument, wodurch der Brückenvertrag erhalten bleibt. Wenn messages und translate beide einen Schlüssel haben, gewinnt messages und translate wird nicht gefragt.

Zahlen, Listen, Sortieren und `lang`

locale deckt mehr als nur Worte ab. Darunter:

Counts werden mit Intl.NumberFormat geschrieben: „1,234 Knoten“ auf Englisch, „1.234 Knoten“ auf Deutsch. Fallback-Englisch verwendet auch die Zahlenformatierung des ausgewählten Gebietsschemas.
Listen von Namen in einem Satz werden mit Intl.ListFormat verbunden: „a, b und c“, „a, b et c“.
Sortierungen in der Tabelle, der Nachbarnliste und dem Pivot-Triage-Bereich verwenden Intl.Collator, sodass „Émile“ neben „Emma“ sortiert wird, Schwedisch „ä“ nach „z“ einfügt und „Element 10“ nach „Element 9“ kommt.

Wenn Sie eine locale deklarieren, erhält das Stammelement des Diagramms diese als lang, ebenso wie die Teile, die die Bibliothek außerhalb des Stammelements bereitstellt (Tooltips, Dropdowns, Vorschlagslisten). Screenreader lesen die Benutzeroberfläche dann mit der richtigen Stimme vor. Ohne locale wird kein lang gesetzt: Der Text der Bibliothek ist Englisch, aber Ihre Daten im Diagramm sind in der Sprache Ihrer Seite und die eigene lang der Seite beschreibt sie am besten.

Das Layout von rechts nach links wird nicht unterstützt: Es gibt keine dir-Behandlung und die Benutzeroberfläche ist in jeder Sprache von links nach rechts angeordnet.

Eine Sprache pro Diagramm

Jeder Graph hat seine eigene Sprache. Zwei Diagramme auf einer Seite können zwei Sprachen verwenden und keine hat Auswirkungen auf die andere.

Ein Diagramm innerhalb eines Diagramms spricht die Sprache seines übergeordneten Diagramms: das innerhalb eines Clusters gezeichnete Unterdiagramm und das kleine Nachbardiagramm in der Seitenleiste.

Der Text, den die Bibliothek in Ihre Daten schreibt, wird einmal in der Sprache des Diagramms geschrieben: die Beschriftung eines Verlaufseintrags („3 Knoten ausgeblendet“) und der Text, mit dem eine neue Notiz beginnt. Wenn Sie das Diagramm in einer anderen Sprache neu erstellen, bleiben diese unverändert.

Im Code: `graph.i18n` und Plugins

graph.i18n ist die Sprache des Diagramms, dasselbe Objekt, mit dem die Bibliothek schreibt:

Mitglied	Was es bewirkt
`locale`	Der verwendete Tag: Ihr oder `'en'`.
`t(key, params?)`	Der Text einer integrierten Nachricht, über die Suche oben.
`formatNumber(value, options?)`	Eine Zahl in den Ziffern des Gebietsschemas. Akzeptiert `Intl.NumberFormat` Optionen.
`formatList(items, options?)`	Als Satz zusammengefügte Elemente. Akzeptiert `Intl.ListFormat` Optionen.
`compare(a, b)`	Ein Komparator in der Reihenfolge des Gebietsschemas, der so wie er ist sicher an `sort` übergeben werden kann.
`collator(options?)`	Die `Intl.Collator` hinter `compare`, standardmäßig numerisch.

Ein Plugin liest das gleiche Objekt wie ctx.i18n. Text, den das Plugin selbst schreibt, ist der zu übersetzende Text des Plugins, eingegeben auf ctx.i18n.locale; Durch Formatieren der Zählungen und Sortieren der Listen nach ctx.i18n bleiben sie mit dem Rest des Diagramms konsistent.

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}`
    },
}

Was bleibt wie es ist

Ihre Daten. Knoten- und Kantenbeschriftungen, Eigenschaftsnamen und Werte werden so gezeichnet, wie sie sind. Ein Eigenschaftsname ohne deklarierte Bezeichnung wird aus seinem Schlüssel in Groß- und Kleinschreibung geschrieben (first_seen lautet „First Seen“); Deklarieren Sie nodePropertiesMap oder edgePropertiesMap, um es in Ihrer Sprache zu benennen. Die Zeile id, die die Eigenschaftslisten über Ihren eigenen Schlüsseln hinzufügen, wird als der Schlüssel geschrieben, um den es sich handelt.
Entwicklertext. Konsolenwarnungen und ausgegebene Fehler bleiben auf Englisch.
Schlüsselglyphen. ⌃ ⇧ ⌥ ⌘ werden so angezeigt, wie sie sind. Schlüsselnamen sind Nachrichten (keys.ctrlCombo, keys.escape), daher kann eine deutsche Schnittstelle Strg+Z sagen.
Abzeichenanzahl am Rand eines Knotens (2k, 99+), die in drei Zeichen passen muss.

Übersetzen der Benutzeroberfläche ​

Gebündelte Sprachen ​

Die Option ​

So wird eine Nachricht gefunden ​

Schlüssel und Nachrichten ​

Text mit Platzhaltern ​

Pluralformen ​

Eine Funktion ​

Bearbeiten von PO-Übersetzungsdateien ​

Starten eines Katalogs von messagesEn ​

Überbrückung Ihrer eigenen Übersetzungsbibliothek ​

Zahlen, Listen, Sortieren und lang ​

Eine Sprache pro Diagramm ​

Im Code: graph.i18n und Plugins ​

Was bleibt wie es ist ​