--- layout: developersguide title: Internationalization --- {% include base.html %} # Internationalization {:.no_toc} In this chapter the openHAB support for internationalization is described. {::options toc_levels="2,3"/} * TOC {:toc} ## Folder and File Structure All texts can be internationalized by using Java i18n properties files. For each language a specific file with a postfix notation is used. The postfix consists of a language code and an optional region code (country code). ``` Format: any__.properties Example: any_de_DE.properties ``` The language code is either two or three lowercase letters that are conform to the ISO 639 standard. The region code (country code) consists of two uppercase letters that are conform to the ISO 3166 standard or to the UN M.49 standard. The search order for those files is the following: ``` any__.properties any_.properties any.properties ``` You can find detailed information about Java internationalization support and a list of the ISO 639 and ISO 3166 codes at [The Java Tutorials](http://docs.oracle.com/javase/tutorial/i18n/locale/create.html) page. The properties files have to be placed in the following directory of the bundle: ``` ESH-INF/i18n ``` Example files: ``` |- ESH-INF |---- i18n |------- yahooweather.properties |------- yahooweather_de.properties |------- yahooweather_de_DE.properties |------- yahooweather_fr.properties ``` ## Internationalize Binding XML files In openHAB a binding developer has to provide different XML files. In these XML files label and description texts must be specified. To Internationalize these texts Java I18N properties files must be defined. For the binding definition and the thing types XML files openHAB defines a standard key scheme, that allows to easily reference the XML nodes. Inside the XML nodes the text must be specified in the default language English. Typically all texts for a binding are put into one file with name of the binding, but they can also be split into multiple files. ### Binding Definition The following snippet shows the binding XML file of the Yahoo Weather Binding and its language file that localizes the binding name and description for the German language. XML file (`binding.xml`): ```xml YahooWeather Binding The Yahoo Weather Binding requests the Yahoo Weather Service to show the current temperature, humidity and pressure. Kai Kreuzer ``` Language file (`yahooweather_de.properties`): ```ini binding.yahooweather.name = Yahoo Wetter Binding binding.yahooweather.description = Das Yahoo Wetter Binding stellt verschiedene Wetterdaten wie die Temperatur, die Luftfeuchtigkeit und den Luftdruck für konfigurierbare Orte vom yahoo Wetterdienst bereit. ``` So the key for referencing the name of a binding is `binding..name` and `binding..description` for the description text. ### Thing Types The following snippet shows an excerpt of the thing type definition XML file of the Yahoo Weather Binding and its language file that localizes labels and descriptions for the German language. XML file (`thing-types.xml`): ```xml Provides various weather data from the Yahoo service Minimum temperature in degrees celsius (metric) or fahrenheit (imperial). Location for the weather information. Syntax is WOEID, see https://en.wikipedia.org/wiki/WOEID. true String Current precipitation (dry, rain, snow). Number Current temperature in degrees celsius (metric) or fahrenheit (imperial). Select the temperature unit. C String Send one of the defined command options to the device. ``` Language file (`yahooweather_de.properties`): ```ini thing-type.yahooweather.weather.label = Wetterinformation thing-type.yahooweather.weather.description = Stellt verschiedene Wetterdaten vom Yahoo Wetterdienst bereit. thing-type.config.yahooweather.weather.location.label = Ort thing-type.config.yahooweather.weather.location.description = Ort der Wetterinformation. Syntax ist WOEID, siehe https://en.wikipedia.org/wiki/WOEID. channel-type.yahooweather.precipitation.label = Niederschlag channel-type.yahooweather.precipitation.description = Aktueller Niederschlag (Trocken, Regen, Schnee). channel-type.yahooweather.precipitation.state.option.dry = Trocken channel-type.yahooweather.precipitation.state.option.rain = Regen channel-type.yahooweather.precipitation.state.option.snow = Schnee channel-type.yahooweather.temperature.label = Temperatur channel-type.yahooweather.temperature.description = Aktuelle Temperatur in Grad Celsius (Metrisch) oder Grad Fahrenheit (US). channel-type.yahooweather.temperature.state.pattern = %d Wert thing-type.yahooweather.weather.channel.minTemperature.label = Min. Temperatur thing-type.yahooweather.weather.channel.minTemperature.description = Minimale Temperatur in Grad Celsius (Metrisch) oder Grad Fahrenheit (US). channel-type.config.yahooweather.temperature.unit.label = Temperatur Einheit channel-type.config.yahooweather.temperature.unit.description = Auswahl der gewünschten Temperatur Einheit. channel-type.config.yahooweather.temperature.unit.option.C = Grad Celsius channel-type.config.yahooweather.temperature.unit.option.F = Grad Fahrenheit channel-type.yahooweather.cmd-channel.command.option.RESET = Reset Device channel-type.yahooweather.cmd-channel.command.option.CMD1 = Command one channel-type.yahooweather.cmd-channel.command.option.CMD2 = Command two ``` So the key for referencing a label of a defined thing type is `thing-type...label`. A label of a channel type can be referenced with `channel-type...label` and a label of a channel definition with `thing-type...channel..label`. And finally the config description parameter key is `thing-type.config....label` or `channel-type.config....label`. The following snippet shows an excerpt of the thing type definition XML file of the Weather Underground Binding and its language file that localizes labels and descriptions for the French language. XML file (`thing-types.xml`): ```xml Provides various weather data from the Weather Underground service This is the weather forecast for tomorrow This is the weather forecast in two days password API key to access the Weather Underground service Multiple syntaxes are supported. Please read the binding documentation for more information Language to be used by the Weather Underground service Specifies the refresh interval in minutes. 30 This is the current weather This is the weather forecast Forecasted temperature String Weather current conditions Number Current temperature Temperature Select the temperature unit provided by the Weather Underground service C Number Maximum temperature Temperature Select the maximum temperature unit provided by the Weather Underground service C ``` Language file (`weatherunderground_fr.properties`): ```ini # binding binding.weatherunderground.name = Extension WeatherUnderground binding.weatherunderground.description = L'extension Weather Underground interroge le service Weather Underground pour récupérer des données météo. # thing types thing-type.weatherunderground.weather.label = Informations météo thing-type.weatherunderground.weather.description = Présente diverses données météo fournies par le service Weather Underground. # thing type configuration thing-type.config.weatherunderground.weather.apikey.label = Clé d'accès thing-type.config.weatherunderground.weather.apikey.description = La clé d'accès au service Weather Underground. thing-type.config.weatherunderground.weather.location.label = Emplacement des données météo thing-type.config.weatherunderground.weather.location.description = Plusieurs syntaxes sont possibles. Merci de consulter la documentation de l'extension pour plus d'information. thing-type.config.weatherunderground.weather.language.label = Langue thing-type.config.weatherunderground.weather.language.description = La langue à utiliser par le service Weather Underground. thing-type.config.weatherunderground.weather.language.option.EN = Anglais thing-type.config.weatherunderground.weather.language.option.FR = Français thing-type.config.weatherunderground.weather.language.option.DL = Allemand thing-type.config.weatherunderground.weather.refresh.label = Fréquence de rafraîchissement thing-type.config.weatherunderground.weather.refresh.description = La fréquence de rafraîchissement des données en minutes. # channel group types channel-group-type.weatherunderground.current.label = Météo actuelle channel-group-type.weatherunderground.current.description = La météo actuelle. channel-group-type.weatherunderground.forecast.label = Météo prévue channel-group-type.weatherunderground.forecast.description = La météo prévue. # channel groups thing-type.weatherunderground.weather.group.forecastTomorrow.label = Météo de demain thing-type.weatherunderground.weather.group.forecastTomorrow.description = La météo prévue demain. thing-type.weatherunderground.weather.group.forecastDay2.label = Météo dans 2 jours thing-type.weatherunderground.weather.group.forecastDay2.description = La météo prévue dans 2 jours. # channel types channel-type.weatherunderground.currentConditions.label = Conditions actuelles channel-type.weatherunderground.currentConditions.description = Les conditions météo actuelles. channel-type.weatherunderground.temperature.label = Température channel-type.weatherunderground.temperature.description = La température actuelle. channel-type.weatherunderground.maxTemperature.label = Température maximale channel-type.weatherunderground.maxTemperature.description = La température maximale. # channels inside a channel group type channel-group-type.weatherunderground.current.channel.temperature.label = Température channel-group-type.weatherunderground.current.channel.temperature.description = La température prévue. # channel type configuration channel-type.config.weatherunderground.temperature.SourceUnit.label = Unité de température channel-type.config.weatherunderground.temperature.SourceUnit.description = Choix de l'unité de température fournie par le service Weather Underground pour la température actuelle. channel-type.config.weatherunderground.temperature.SourceUnit.option.C = Degrés Celsius channel-type.config.weatherunderground.temperature.SourceUnit.option.F = Degrés Fahrenheit channel-type.config.weatherunderground.maxTemperature.SourceUnit.label = Unité de température maximale channel-type.config.weatherunderground.maxTemperature.SourceUnit.description = Choix de l'unité de température fournie par le service Weather Undergroundde pour la température maximale. channel-type.config.weatherunderground.maxTemperature.SourceUnit.option.C = Degrés Celsius channel-type.config.weatherunderground.maxTemperature.SourceUnit.option.F = Degrés Fahrenheit ``` So the label of a channel group type can be referenced with `channel-group-type...label` and the label of a channel group definition with `thing-type...group..label`. A label of a channel definition inside a channel group type can be translated with `channel-group-type...channel..label`. ### Discovery A binding can provide localized labels for discovery results. Use any English label of your choice to create your `DiscoveryResult`: ```java DiscoveryResult discoveryResult = DiscoveryResultBuilder.create(thingUID).withProperties(properties) .withBridge(bridgeUID).withLabel("Local Weather And Forecast").build(); ``` In this case it is mandatory to define a language file for the English language. Add the same label to this default properties file (e.g. `darksky.properties`): ```ini # discovery result discovery.darksky.weather-and-forecast.api.local.label = Local Weather And Forecast ``` The pattern follows this pattern: `discovery.....label = `. The `` is optional and only needed if your Binding implements a Bridge / Thing structure. Add as much translations as you like in separate Language files (e.g. `darksky_de.properties`): ```ini # discovery result discovery.darksky.weather-and-forecast.api.local.label = Lokales Wetter und Wettervorhersage ``` ### Using custom Keys In addition to the default keys the developer can also specify custom keys inside the XML file. But with this approach the XML file cannot longer contain the English texts. So it is mandatory to define a language file for the English language. The syntax for custom keys is `@text/`. The keys are unique across the whole bundle, so a constant can reference any key in all files inside the `ESH-INF/i18n` folder. The following snippet shows a binding XML that uses custom keys: XML file (`binding.xml`): ```xml @text/bindingName @text/bindingName Kai Kreuzer ``` Language file (`yahooweather_en.properties`): ```ini bindingName = Yahoo Weather Binding offline.communication-error=The Yahoo Weather API is currently not available. ``` Language file (`yahooweather_de.properties`): ```ini bindingName = Yahoo Wetter Binding offline.communication-error=Die Yahoo Wetter API ist zur Zeit nicht verfügbar. ``` The custom keys are a very good practice to translate bundle dependent error messages. ```java updateStatus(ThingStatus.OFFLINE, ThingStatusDetail.OFFLINE.COMMUNICATION_ERROR, "@text/offline.communication-error"); ``` ## I18n Text Provider API To programmatically resolve texts for certain languages openHAB provides the OSGi service `TranslationProvider`. The service parses every file inside the `ESH-INF/i18n` folder and caches all texts. A localized text can be retrieved via the method `getText(Bundle bundle, String key, String default, Locale locale)` (or via the method `getText(Bundle bundle, String key, String default, Locale locale, Object... arguments)` if additional arguments are to be injected into the localized text), where bundle must be the reference to the bundle, in which the file is stored. The BundleContext from the Activator provides a method to get the bundle. ```java String text = i18nProvider.getText(bundleContext.getBundle(), "my.key", "DefaultValue", Locale.GERMAN); ``` ## Locale Provider To programmatically fetch the locale used by the openHAB system an OSGi service `LocaleProvider` is offered. The service contains a `getLocale()` method that can be used to choose a configurable locale. ## Getting Thing Types and Binding Definitions in different languages Thing types can be retrieved through the `ThingTypeRegistry` OSGi service. Every method takes a `Locale` as last argument. If no locale is specified the thing types are returned for the default locale which is determined by using the `LocaleProvider`, or the default text, which is specified in the XML file, if no language file for the default locale exists. The following snippet shows how to retrieve the list of Thing Types for the German locale: ```java List thingTypes = thingTypeRegistry.getThingTypes(Locale.GERMAN); ``` If one binding supports the German language and another does not, it might occur that the languages of the returned thing types are mixed. For Binding Info and ConfigDescription, the localized objects can be retrieved via the `BindingInfoRegistry` and the `ConfigDescriptionRegistry` in the same manner as described for Thing Types.