From 82a9aa1d98244a49d0a59405f9eb84553ca1ffaa Mon Sep 17 00:00:00 2001 From: Adam Mills Date: Sat, 3 Mar 2018 11:06:10 -0500 Subject: [PATCH] Improved docs for the i18n project (#4796) --- .../asides/developers_navigation.html | 9 ++++++++- .../backend_localization.markdown | 19 ++++++++++++++++++ .../custom_component_localization.markdown | 20 +++++++++++++++++++ .../internationalization/index.markdown | 19 ++++++++++++++++++ .../translation.markdown} | 5 +++-- 5 files changed, 69 insertions(+), 3 deletions(-) create mode 100644 source/developers/internationalization/backend_localization.markdown create mode 100644 source/developers/internationalization/custom_component_localization.markdown create mode 100644 source/developers/internationalization/index.markdown rename source/developers/{frontend_translation.markdown => internationalization/translation.markdown} (97%) diff --git a/source/_includes/asides/developers_navigation.html b/source/_includes/asides/developers_navigation.html index 0f42206817a..2d770cb7a14 100644 --- a/source/_includes/asides/developers_navigation.html +++ b/source/_includes/asides/developers_navigation.html @@ -78,7 +78,14 @@
  • {% active_link /developers/frontend_add_more_info/ Add More Info Dialog %}
  • {% active_link /developers/frontend_creating_custom_panels/ Add Custom Panels %}
  • {% active_link /developers/frontend_creating_custom_ui/ Add Custom UI %}
    • -
  • {% active_link /developers/frontend_translation/ Translation %}
    • + + +
  • + {% active_link /developers/internationalization/ Internationalization %} +
  • diff --git a/source/developers/internationalization/backend_localization.markdown b/source/developers/internationalization/backend_localization.markdown new file mode 100644 index 00000000000..6d395352b4f --- /dev/null +++ b/source/developers/internationalization/backend_localization.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Backend Localization" +description: "Translating platforms in Home Assistant" +date: 2018-03-01 18:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: 0.64 +--- + +## {% linkable_title Translation Strings %} +Platform translation strings are stored as JSON in the [home-assistant](https://github.com/home-assistant/home-assistant) repository. These files must be located adjacent to the component/platform they belong to. They are named `strings..json`, unless the component being translated exists in its own directory, in which case the file is simply named `strings.json` in that directory. This file will contain the different strings that will be translatable. Currently only states are supported by the frontend. + +After the pull request with the strings file is merged into the `dev` branch, the strings will be automatically uploaded to Lokalise, where contributors can submit translations. The translated strings in Lokalise will be periodically pulled in to the home-assistant repository. + +## {% linkable_title States Localization %} +The first step when localizing platform states is to ensure that the states defined in the actual platform code are defined in `snake_case`. The states should not contain capital letters or spaces. Next, the strings file needs to be created. The states should exist under the `state` key, and map the backend state keys to their English translations. [The season sensor localization](https://github.com/home-assistant/home-assistant/pull/12453/commits/bb2f328ce10c3867990e34a88da64e2f8dc7a5c4) is a good example. diff --git a/source/developers/internationalization/custom_component_localization.markdown b/source/developers/internationalization/custom_component_localization.markdown new file mode 100644 index 00000000000..b7d12664d4d --- /dev/null +++ b/source/developers/internationalization/custom_component_localization.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "Custom Component Localization" +description: "Translating custom components in Home Assistant" +date: 2018-03-01 18:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: 0.64 +--- + +## {% linkable_title Translation Strings %} +Unlike localized strings merged in the home-assistant repository, custom components cannot take advantage of Lokalise for user submitted translations. However, custom component authors can still include translation with their components. These will be read from the `.translations` directory, adjacent to the component source file. They are named `..json`, unless the custom component exists in its own directory, in which case the file is simply named `.json` in the `.translations` directory. + +These files follow the same formatting as [backend translation string files](/developers/internationalization/backend_localization/), but a copy will exist for each translated language. + +The language codes follow the [BCP47](https://tools.ietf.org/html/bcp47) format. The [frontend translation files](https://github.com/home-assistant/home-assistant-polymer/tree/master/translations) can also be referred to if you are unsure of the correct language code to use. + +The frontend will serve these files after Home Assistant is restarted. diff --git a/source/developers/internationalization/index.markdown b/source/developers/internationalization/index.markdown new file mode 100644 index 00000000000..109502fe458 --- /dev/null +++ b/source/developers/internationalization/index.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Internationalization" +description: "Home Assistant internationalization summary" +date: 2018-03-01 18:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: 0.64 +--- + +The Home Assistant internationalization project includes preparing platforms and the frontend for localization, as well as the actual translation of localized strings. + +Some compmonents and platforms will have strings that need to be localized specifically for that platform. These strings are managed in the core [home-assistant](https://github.com/home-assistant/home-assistant) repository. The Home Assistant backend will serve strings to the clients based on the loaded components in the running instance. + +There are also localizable strings that exist only on the frontend. These strings are managed in the [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer) repository. These strings are stored with the frontend and don’t depend on the backend configuration. + +Our strings are translated by the community using the online translation tool [Lokalise](https://lokalise.co/). diff --git a/source/developers/frontend_translation.markdown b/source/developers/internationalization/translation.markdown similarity index 97% rename from source/developers/frontend_translation.markdown rename to source/developers/internationalization/translation.markdown index c91d80e36ed..334a68e6aa3 100644 --- a/source/developers/frontend_translation.markdown +++ b/source/developers/internationalization/translation.markdown @@ -1,13 +1,14 @@ --- layout: page -title: "Frontend Translation" -description: "How to translate the frontend for Home Assistant." +title: "Translation" +description: "How to translate Home Assistant." date: 2017-10-27 13:00 sidebar: true comments: false sharing: true footer: true ha_release: 0.57 +redirect_from: /developers/frontend_translation/ --- ## {% linkable_title How to start %}