Added information about i18n of Discovery Results (#1109)
* Added section about "Internationalization of Discovery Services" - Added section about "Internationalization of Discovery Services" Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de> * Added section about "Discovery Results" - Added section about "Discovery Results" Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de> * Update developers/utils/i18n.md Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de> * Update developers/utils/i18n.md Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>pull/1115/head
Christoph Weitkamp
Jerome Luckenbach
parent
e8bcb882d2
commit
b714008d16
|
|
@ -539,11 +539,11 @@ Currently the framework provides two base thing handler implementations for the
|
|||
|
||||
Sub-classes of these handlers must only override the operation `getConfigStatus` to provide the configuration status in form of a collection of `org.eclipse.smarthome.config.core.status.ConfigStatusMessage`s.
|
||||
|
||||
#### Internationalizing
|
||||
#### Internationalization
|
||||
|
||||
The framework will take care of internationalizing messagess.
|
||||
The framework will take care of internationalizing messages.
|
||||
|
||||
For this purpose there must be an i18n properties file inside the bundle of the configuration status provider that has a message declared for the message key of the `ConfigStatusMessage`.
|
||||
For this purpose there must be an [i18n](../utils/i18n.html) properties file inside the bundle of the configuration status provider that has a message declared for the message key of the `ConfigStatusMessage`.
|
||||
The actual message key is built by the operation `withMessageKeySuffix(String)` of the message´s builder in the manner that the given message key suffix is appended to *config-status."config-status-message-type."*.
|
||||
|
||||
As a result depending on the type of the message the final constructed message keys are:
|
||||
|
|
@ -614,7 +614,7 @@ You are now free to specify as many actions as you want in `MqttActions`.
|
|||
|
||||
In the following example we provide a "publishMQTT" action.
|
||||
An action must be annotated with `@RuleAction`, a label and a description must be provided.
|
||||
In this case we refer to translation, see [i18n](utils/i18n.html) support, instead of directly providing a string.
|
||||
In this case we refer to translation, see [i18n](../utils/i18n.html) support, instead of directly providing a string.
|
||||
|
||||
```java
|
||||
@RuleAction(label = "@text/actionLabel", description = "@text/actionDesc")
|
||||
|
|
@ -695,10 +695,10 @@ This list will be given to the constructor of `AbstractDiscoveryService` and can
|
|||
The `Discovery` class of a binding which implements `AbstractDiscoveryService` should be annotated with
|
||||
|
||||
```java
|
||||
@Component(service = DiscoveryService.class, immediate = true, configurationPid = "discovery.<bindingID>")
|
||||
@Component(service = DiscoveryService.class, immediate = true, configurationPid = "discovery.<binding-id>")
|
||||
```
|
||||
|
||||
where `<bindingID>` is the id of the binding, i.e. `astro` for the Astro binding.
|
||||
where `<binding-id>` is the id of the binding, i.e. `astro` for the Astro binding.
|
||||
Such a registered service will be picked up automatically by the framework.
|
||||
|
||||
### Background Discovery
|
||||
|
|
@ -772,6 +772,22 @@ If this behavior is not appropriate for the implemented discovery service, one c
|
|||
}
|
||||
```
|
||||
|
||||
### Internationalization
|
||||
|
||||
The framework will take care of internationalizing labels of discovery results if you extend the `AbstractDiscoveryService`.
|
||||
See [i18n](../utils/i18n.html#discovery) for more information.
|
||||
|
||||
::: tip Hint!
|
||||
To make it work you have to inject references to the `LocaleProvider` and the `TranslationProvider` services into your implementation.
|
||||
The `AbstractDiscoveryService` already provides `protected` properties, which are not yet linked to a service.
|
||||
The devoloper has to take care about that.
|
||||
|
||||
```java
|
||||
protected @NonNullByDefault({}) TranslationProvider i18nProvider;
|
||||
protected @NonNullByDefault({}) LocaleProvider localeProvider;
|
||||
```
|
||||
:::
|
||||
|
||||
### UPnP Discovery
|
||||
|
||||
UPnP discovery is implemented in the framework as `UpnpDiscoveryService`.
|
||||
|
|
|
|||
|
|
@ -6,10 +6,17 @@ title: Internationalization
|
|||
{% include base.html %}
|
||||
|
||||
# Internationalization
|
||||
{:.no_toc}
|
||||
|
||||
In this chapter the openHAB support for internationalization is described.
|
||||
|
||||
All texts can be internationalized by using Java I18N properties files.
|
||||
{::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).
|
||||
|
||||
|
|
@ -42,6 +49,7 @@ Example files:
|
|||
```
|
||||
|- ESH-INF
|
||||
|---- i18n
|
||||
|------- yahooweather.properties
|
||||
|------- yahooweather_de.properties
|
||||
|------- yahooweather_de_DE.properties
|
||||
|------- yahooweather_fr.properties
|
||||
|
|
@ -61,7 +69,7 @@ Typically all texts for a binding are put into one file with name of the binding
|
|||
|
||||
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 file (`binding.xml`):
|
||||
|
||||
```xml
|
||||
<binding:binding id="yahooweather">
|
||||
|
|
@ -72,7 +80,7 @@ XML file (binding.xml):
|
|||
</binding:binding>
|
||||
```
|
||||
|
||||
Language file (yahooweather_de.properties):
|
||||
Language file (`yahooweather_de.properties`):
|
||||
|
||||
```ini
|
||||
binding.yahooweather.name = Yahoo Wetter Binding
|
||||
|
|
@ -85,7 +93,7 @@ So the key for referencing the name of a binding is `binding.<binding-id>.name`
|
|||
|
||||
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 file (`thing-types.xml`):
|
||||
|
||||
```xml
|
||||
<thing:thing-descriptions bindingId="yahooweather">
|
||||
|
|
@ -151,10 +159,9 @@ XML file (thing-types.xml):
|
|||
</command>
|
||||
</channel-type>
|
||||
</thing:thing-descriptions>
|
||||
|
||||
```
|
||||
|
||||
Language file (yahooweather_de.properties):
|
||||
Language file (`yahooweather_de.properties`):
|
||||
|
||||
```ini
|
||||
thing-type.yahooweather.weather.label = Wetterinformation
|
||||
|
|
@ -192,7 +199,7 @@ And finally the config description parameter key is `thing-type.config.<binding-
|
|||
|
||||
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 file (`thing-types.xml`):
|
||||
|
||||
```xml
|
||||
<thing:thing-descriptions bindingId="weatherunderground">
|
||||
|
|
@ -309,7 +316,7 @@ XML file (thing-types.xml):
|
|||
</thing:thing-descriptions>
|
||||
```
|
||||
|
||||
Language file (weatherunderground_fr.properties):
|
||||
Language file (`weatherunderground_fr.properties`):
|
||||
|
||||
```ini
|
||||
# binding
|
||||
|
|
@ -366,12 +373,38 @@ channel-type.config.weatherunderground.maxTemperature.SourceUnit.label = Unité
|
|||
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.<binding-id>.<channel-group-type-id>.label` and the label of a channel group definition with `thing-type.<binding-id>.<thing-type-id>.group.<channel-group-id>.label`.
|
||||
A label of a channel definition inside a channel group type can be translated with `channel-group-type.<binding-id>.<channel-group-type-id>.channel.<channel-id>.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.<binding-id>.<thing-type-id>.<bridge-id>.<thing-id>.label = <your-translated-label>`.
|
||||
The `<bridge-id>` 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.
|
||||
|
|
@ -382,7 +415,7 @@ The keys are unique across the whole bundle, so a constant can reference any key
|
|||
|
||||
The following snippet shows a binding XML that uses custom keys:
|
||||
|
||||
XML file (binding.xml):
|
||||
XML file (`binding.xml`):
|
||||
|
||||
```xml
|
||||
<binding:binding id="yahooweather">
|
||||
|
|
@ -392,7 +425,7 @@ XML file (binding.xml):
|
|||
</binding:binding>
|
||||
```
|
||||
|
||||
Language file (yahooweather_en.properties):
|
||||
Language file (`yahooweather_en.properties`):
|
||||
|
||||
```ini
|
||||
bindingName = Yahoo Weather Binding
|
||||
|
|
@ -400,7 +433,7 @@ bindingName = Yahoo Weather Binding
|
|||
offline.communication-error=The Yahoo Weather API is currently not available.
|
||||
```
|
||||
|
||||
Language file (yahooweather_de.properties):
|
||||
Language file (`yahooweather_de.properties`):
|
||||
|
||||
```ini
|
||||
bindingName = Yahoo Wetter Binding
|
||||
|
|
|
|||
Loading…
Reference in New Issue