Mehrsprachigkeit

Sprachen festlegen

Bevor Felder mehrsprachig gepflegt werden können, müssen die unterstützten Sprachen des Namensraums festgelegt werden. Dazu wird im Namensraum eine API mit dem festen Namen languages angelegt. Alle APIs dieses Namensraums können sie dann nutzen.

{
    "fields": {
        "code": {
            "cms": {
                "column": true,
                "unique": true
            },
            "empty": false,
            "type": "string"
        },
        "display": {
            "cms": {
                "column": true
            },
            "type": "string",
            "optional": true
        }
    },
    "hideId": true
}

curl -X POST -u "$USER" -H 'Content-Type: application/json' -d @languages.json "$CMS/schema/tutorial/languages"

curl -X POST -u "$USER" -H 'Content-Type: application/json' -d '{ "code": "de", "display": "Deutsch" }' "$CMS/data/tutorial/languages"
curl -X POST -u "$USER" -H 'Content-Type: application/json' -d '{ "code": "en", "display": "English" }' "$CMS/data/tutorial/languages"
curl -X POST -u "$USER" -H 'Content-Type: application/json' -d '{ "code": "fr", "display": "Français" }' "$CMS/data/tutorial/languages"

• code muss vorhanden sein: eine Pflicht-Zeichenkette, eindeutig (unique) und nicht leer (empty). Verwendet werden sollten Standardkürzel wie en, de oder fr.
• display wird dringend empfohlen. Die Pflegeanwendung zeigt diesen Namen bei der Sprachauswahl an, sonst den code.
• Weitere Felder können nach Bedarf ergänzt werden.

en hat in der Pflegeanwendung eine besondere Bedeutung: Es ist die Startsprache, wenn die API keine defaultLanguage angibt (siehe Konfiguration von APIs), und lokalisierbare Spalten der Liste zeigen den englischen Wert. Beim Ausliefern der Daten fällt das CMS nicht automatisch auf eine andere Sprache zurück. Fehlt eine Übersetzung, muss die Anwendung selbst entscheiden, was sie anzeigt.

Wer mehrsprachige Datensätze abfragt oder schreibt, braucht auch Leserecht auf die API languages des Namensraums (siehe Rechte).

Mehrsprachige Felder

Grundsätzlich kann jedes Feld als lokalisierbar gekennzeichnet werden ("localizable": true), außer GEO-Koordinaten.

{
    "fields": {
        "name": {
            "cms": {
                "column": true
            },
            "empty": false,
            "type": "string"
        },
        "title": {
            "cms": {
                "column": true
            },
            "type": "string",
            "localizable": true,
            "optional": true,
            "empty": false
        }
    }
}

name ist eine Pflicht-Zeichenkette, title ist optional, darf nicht leer sein und ist lokalisierbar.

Die Pflegeanwendung bietet die in languages definierten Sprachen zur Umschaltung an. Ein Symbol hinter dem Feldnamen kennzeichnet title als lokalisierbar. Über die Sprachumschaltung werden die Varianten eingegeben.

In der Liste zeigt eine lokalisierbare Spalte immer den Wert der Variante en.

Eine API kann mehrere lokalisierbare Felder haben, auch Dateien:

{
    "fields": {
        "name": {
            "cms": {
                "column": true
            },
            "empty": false,
            "type": "string"
        },
        "title": {
            "cms": {
                "column": true
            },
            "type": "string",
            "localizable": true,
            "optional": true,
            "empty": false
        },
        "image": {
            "type": "file",
            "localizable": true,
            "optional": true
        }
    }
}

Die Sprachumschaltung zeigt den Datensatz aus Sicht der gewählten Sprache: Alle lokalisierbaren Felder erscheinen in dieser Sprache.

Lokalisierbare Strukturen

Für das Beispiel gibt es auch einen anderen Ansatz:

{
    "fields": {
        "name": {
            "cms": {
                "column": true
            },
            "empty": false,
            "type": "string"
        },
        "image": {
            "type": "object",
            "optional": true,
            "localizable": true,
            "strict": true,
            "properties": {
                "title": {
                    "type": "string",
                    "optional": true,
                    "empty": false
                },
                "content": {
                    "type": "file",
                    "optional": true
                }
            }
        }
    }
}

Hier sind Bild (content) und Beschreibung (title) in einer Substruktur image zusammengefasst. Die Sprachumschaltung betrifft dann die Struktur als Ganzes. Wird sie erweitert, sind neue Felder automatisch Teil der Lokalisierung. Je nach Anwendung ist der eine oder andere Ansatz nützlicher, eventuell auch eine Kombination.

Das Lokalisierungssymbol zeigt, dass die Umschaltung tatsächlich nur die ganze Struktur image betrifft, nicht die darin enthaltenen Felder title und content.

Einschränkung

Die Felder innerhalb einer lokalisierten Struktur zusätzlich lokalisierbar zu machen, ist derzeit wenig sinnvoll: Die Sprachumschaltung betrifft immer alle Felder gleichermaßen. Ist Deutsch gewählt, können in der deutschen Variante der Struktur auch nur die deutschen Varianten von title und content gepflegt werden, für Englisch nur die englischen und so weiter.

Darstellung in der Schnittstelle

Ist ein Feld lokalisierbar, wird in der Schnittstelle statt des Werts immer ein Objekt übertragen. Seine Schlüssel sind die Sprachkürzel, die Werte entsprechen dem Datentyp des Felds.

{
    "name": "Deutschland"
}

wird bei lokalisierbarem name zu:

{
    "name": {
        "de": "Deutschland",
        "en": "Germany",
        "fr": "Allemagne"
    }
}

Erlaubt sind nur Sprachkürzel, die in der API languages des Namensraums eingetragen sind. Ein unbekanntes Kürzel wird abgewiesen, z. B. The object 'name' contains forbidden keys: 'fr'. Nicht jede Sprache muss gefüllt sein. Auch mit ?exported liefert das CMS alle vorhandenen Sprachen, die Auswahl trifft die Anwendung.

In Abfragen wird die Sprache mit Punkt an den Feldnamen gehängt, z. B. name.de.