A Topincs store can be operated in multiple languages as a multilingual store. But even a store running in a single language, a monolingual store, can partially support additional languages, e.g. for PDF generation. The key difference here is whether the user interface is available in one or many languages. This article introduces all the concepts necessary for an administrator to successfully fullfill internationalisation requirements.
A multilingual store uses primarily Content-Negotiation to determine the user interface language. The Accept-Language header of the HTTP request is used to select the most fitting language from the languages the store supports, the store languages. This can be overridden in two ways: a user account may be connected to a language or the URL might be tied to a language, e.g. by using the lang
parameter. In both cases the browser is pinned permanently to the language with a cookie, until there is another override or the browser is closed. This pinning affects only pages of the store in question and has otherwise no effect.
When a user account is connected to a language, the user interface language is switched only after login, thus the language of the login dialog will be based on the browser's language settings. In some cases this problem can be avoided by providing a personalized login URL with a ticket to the user.
Hint: You for sure have encountered scoped names and occurrences during modeling. On the schema level all labels and descriptions are language scoped.
The Topic Maps Data Model offers one ingredient which simplifies the support of multiple languages a great deal: Scope. Since natural language only may occur in the values of names and textual occurrences, scoping the respective types by language, a predefined topic type, is all you have to do in the schema of your store. You realize this by creating a scope constraint.
The children of the world speak many languages. So Santa needs his system to run in multiple languages. It currently only supports English. We need to create the scope constraints and increase the maximum cardinality of the respective topic name/occurrence constraints, e.g. Country must have multiple names, for each supported language one.
Check it out
Hint: A single dedicated topic name type for all multilingual topic types, usually the master data, will suffice. We recommend to name it Label.
API reference
Every topic in the store has a label. In a monolingual store there is a single label per topic. In a multilingual store supporting n languages, there is n labels per topic. The label can be the value of a name or the result of a computation when there is a label rule defined for the topic type. In a multilingual store the appropriate label is selected automatically in the user interface and by the label
method of a tobject. Also label rules can be scoped by language. But there is more to it. After all our system is not only composed of references to topics.
The other area where natural language texts are introduced in the system is programming. The headline of a HTML page, or the subject of an email, the text in a PDF document are typically places where the administrator uses natural language to create structure and offer guidance and meaning to the users.
API reference
The approach here is simple. Instead of writing down the actual text in a specific natural language, use the txt
function provided by Topincs. This function works together with the predefined topic type Text which is simply a mapping from a key to mutiple translations. Pass the key to txt
and it gives you the appropriate translation.
Check it out
Check it out
Check it out
echo txt("hello_world");
// Hello, World!
// Hallo, Welt!
echo txt("born_on", $date->format(txt("date_format")));
// Born on 05/07/2006
// Geboren am 07.05.2006
API reference
Warning: The txt
function accepts the system id of a language to achieve the same result. This remains supported, but it is recommened to use lang
instead.
In some systems it becomes necessary to generate a document in a language different from the user interface, e.g. a user working in German wants to send an invoice to an Englisch speaking customer. The lang
function allows to switch language during execution temporarily without changing the user interface language permanantly. This selection remains active until the next call to lang
or the end of the PHP runtime.
// This user works in English:
echo txt("hello_world");
// Hello, World!
// Switch to German:
lang("de");
echo txt("hello_world");
// Hallo, Welt!
// If necessary due to more output to UI, revert by passing nothing:
lang();
echo txt("hello_world");
// Hello, World!
When there is language scoped names or occurrences on a topic, it is not possible to retrieve the appropriate one with a get
call, since this will always return the first statement of that type. In order to retrieve the right one, there is an additional method family prefixed with txt
, e.g. use txt_description
instead of get_description
.
Santa wants to provide descriptions of the gifts to the kids. So we create an occurrence type Description on the topic type Gift, create the respective scope constraint, and adjust the programming interface of Gift.
Check it out
Check it out
$ball = Tobject::get("id:1273");
// This returns the first description:
$ball->get_description();
// Returns the description that matches the current languge:
$ball->txt_description();
Hint: By default the store language is English. Get in touch when you need this changed.
To create a multilingual system in Topincs you need to use scoped names and occurrences. During coding you need to avoid hardcoded strings in natural language and replace them by calls to the txt
function. Topincs currently supports Dutch, English, French, German, Italian, Polish, and Serbian. If your language is not in this list, get in touch.
This page cannot be displayed in your browser. Use Firefox, Opera, Safari, or Chrome instead.
Saving …