From f60e82453f8fc6c5ee9dbf61fad2bfb22c07a7bc Mon Sep 17 00:00:00 2001 From: rosch100 Date: Tue, 2 Dec 2025 13:58:39 +0100 Subject: [PATCH 1/6] Add documentation for multilingual README support and complete hacs.json keys - Add documentation for multilingual README support in publisher and user docs - Add missing hacs.json keys: render_readme and supported_languages - Update country key documentation to reflect support for both string and list types --- source/docs/publish/start.md | 8 ++++++-- source/docs/use/repositories/dashboard.md | 1 + 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/source/docs/publish/start.md b/source/docs/publish/start.md index 0cb22424..016684b7 100644 --- a/source/docs/publish/start.md +++ b/source/docs/publish/start.md @@ -30,6 +30,8 @@ Your repository on GitHub needs to have [topics](https://docs.github.com/en/gith Your repository needs to have a [readme](https://github.com/matiassingers/awesome-readme) with information about how to use it. +HACS supports multilingual README files. To provide documentation in multiple languages, use the naming pattern `README.{language_code}.md` (e.g., `README.de.md` for German, `README.fr.md` for French). HACS automatically displays the README matching the user's Home Assistant language setting, falling back to the default `README.md` if no language-specific version is available. + ### hacs.json This is a special manifest file that defines the information that HACS shows in the UI and what files/paths that HACS should use. _This file must be located in the root of your repository._ @@ -40,13 +42,15 @@ The following keys are supported: | ---------------------- | :----: | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | The display name that will be used in the HACS UI. | | `content_in_root` | bool | No | Indicates whether the content is in the root of the repository as opposed to in a subdirectory. | -| `zip_release` | bool | No | Indicates whether the content is in a zipped archive when releases are published on GitHub. If you use this you also need to add `filename`. **This is only supported for integrations.** | +| `zip_release` | bool | No | Indicates whether the content is in a zipped archive when releases are published on GitHub. If you use this you also need to add `filename`. **This is only supported for integrations.** | | `filename` | string | No | Name of the file HACS should look for, only applies to single item types (plugin, theme, template, python_scripts, zip_release). | | `hide_default_branch` | bool | No | Tells HACS to not offer downloading the default branch. | -| `country` | string | No | Two character country code in ISO 3166-1 alpha-2 format. [ISO 3166-1 alpha-2 on Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | +| `country` | string/list | No | Two character country code(s) in ISO 3166-1 alpha-2 format. Can be a single country code or a list of country codes. [ISO 3166-1 alpha-2 on Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | | `homeassistant` | string | No | The minimum required Home Assistant version. | | `hacs` | string | No | The minimum required HACS version. | | `persistent_directory` | string | No | A relative path (within the integration directory) that will be kept safe during upgrades. \_Can only be used with integrations.\* | +| `render_readme` | bool | No | Indicates whether the README file should be used as the information file. If `false`, HACS will look for `info` or `info.md` files instead. | +| `supported_languages` | list | No | List of supported language codes (e.g., `["de", "fr", "es"]`) for multilingual README files. Language codes must be 2-letter ISO 639-1 codes. If specified, HACS will validate that corresponding `README.{lang}.md` files exist. | !!! tip diff --git a/source/docs/use/repositories/dashboard.md b/source/docs/use/repositories/dashboard.md index ea5ca5c7..ad1261e9 100644 --- a/source/docs/use/repositories/dashboard.md +++ b/source/docs/use/repositories/dashboard.md @@ -78,6 +78,7 @@ To use the functionality provided by a repository, you need to download it to Ho 1. In Home Assistant, open HACS and find the repository of interest. 2. Select the repository and view its overview page. - The main section of this view renders the README file of the repository. + - If the repository maintainer has provided multilingual README files, HACS will automatically display the README in your Home Assistant language setting. If no language-specific version is available, the default `README.md` will be shown. - The **badges** on top provide some key information, such as author, [GitHub](https://github.com) stars, and the number of open issues and pull requests. - This page should also contain the documentation on how to use it. - The content depends on the repository [type](/docs/use/repositories/type/index.md) and on the information the author provides. From 78fdf902ab8087182803fac3f245582ee20115bb Mon Sep 17 00:00:00 2001 From: rosch100 Date: Tue, 2 Dec 2025 14:05:34 +0100 Subject: [PATCH 2/6] Fix grammar: complete sentence in country field description --- source/docs/publish/start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/publish/start.md b/source/docs/publish/start.md index 016684b7..8b391fc7 100644 --- a/source/docs/publish/start.md +++ b/source/docs/publish/start.md @@ -45,7 +45,7 @@ The following keys are supported: | `zip_release` | bool | No | Indicates whether the content is in a zipped archive when releases are published on GitHub. If you use this you also need to add `filename`. **This is only supported for integrations.** | | `filename` | string | No | Name of the file HACS should look for, only applies to single item types (plugin, theme, template, python_scripts, zip_release). | | `hide_default_branch` | bool | No | Tells HACS to not offer downloading the default branch. | -| `country` | string/list | No | Two character country code(s) in ISO 3166-1 alpha-2 format. Can be a single country code or a list of country codes. [ISO 3166-1 alpha-2 on Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | +| `country` | string/list | No | Two character country code(s) in ISO 3166-1 alpha-2 format. It can be a single country code or a list of country codes. [ISO 3166-1 alpha-2 on Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | | `homeassistant` | string | No | The minimum required Home Assistant version. | | `hacs` | string | No | The minimum required HACS version. | | `persistent_directory` | string | No | A relative path (within the integration directory) that will be kept safe during upgrades. \_Can only be used with integrations.\* | From 700b3b61cc5bb57017d8651f3fd49b0d451f365a Mon Sep 17 00:00:00 2001 From: rosch100 Date: Tue, 2 Dec 2025 14:26:13 +0100 Subject: [PATCH 3/6] Rename supported_languages to readme_languages and remove validation note - Change key name from supported_languages to readme_languages per review feedback - Remove validation note about README file existence check from documentation --- source/docs/publish/start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/publish/start.md b/source/docs/publish/start.md index 8b391fc7..58348296 100644 --- a/source/docs/publish/start.md +++ b/source/docs/publish/start.md @@ -50,7 +50,7 @@ The following keys are supported: | `hacs` | string | No | The minimum required HACS version. | | `persistent_directory` | string | No | A relative path (within the integration directory) that will be kept safe during upgrades. \_Can only be used with integrations.\* | | `render_readme` | bool | No | Indicates whether the README file should be used as the information file. If `false`, HACS will look for `info` or `info.md` files instead. | -| `supported_languages` | list | No | List of supported language codes (e.g., `["de", "fr", "es"]`) for multilingual README files. Language codes must be 2-letter ISO 639-1 codes. If specified, HACS will validate that corresponding `README.{lang}.md` files exist. | +| `readme_languages` | list | No | List of supported language codes (e.g., `["de", "fr", "es"]`) for multilingual README files. Language codes must be 2-letter ISO 639-1 codes. | !!! tip From 9a93f2d91fcbbe3a7994c0fa99284916e231d6a3 Mon Sep 17 00:00:00 2001 From: rosch100 Date: Tue, 2 Dec 2025 14:31:23 +0100 Subject: [PATCH 4/6] Remove render_readme and revert country to string per review feedback - Remove render_readme key as it's unrelated to this PR - Revert country key back to string type (not string/list) as it's unrelated --- source/docs/publish/start.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/docs/publish/start.md b/source/docs/publish/start.md index 58348296..975d4b75 100644 --- a/source/docs/publish/start.md +++ b/source/docs/publish/start.md @@ -45,11 +45,10 @@ The following keys are supported: | `zip_release` | bool | No | Indicates whether the content is in a zipped archive when releases are published on GitHub. If you use this you also need to add `filename`. **This is only supported for integrations.** | | `filename` | string | No | Name of the file HACS should look for, only applies to single item types (plugin, theme, template, python_scripts, zip_release). | | `hide_default_branch` | bool | No | Tells HACS to not offer downloading the default branch. | -| `country` | string/list | No | Two character country code(s) in ISO 3166-1 alpha-2 format. It can be a single country code or a list of country codes. [ISO 3166-1 alpha-2 on Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | +| `country` | string | No | Two character country code in ISO 3166-1 alpha-2 format. [ISO 3166-1 alpha-2 on Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | | `homeassistant` | string | No | The minimum required Home Assistant version. | | `hacs` | string | No | The minimum required HACS version. | | `persistent_directory` | string | No | A relative path (within the integration directory) that will be kept safe during upgrades. \_Can only be used with integrations.\* | -| `render_readme` | bool | No | Indicates whether the README file should be used as the information file. If `false`, HACS will look for `info` or `info.md` files instead. | | `readme_languages` | list | No | List of supported language codes (e.g., `["de", "fr", "es"]`) for multilingual README files. Language codes must be 2-letter ISO 639-1 codes. | From 8b475a68750ba0c074917a63ca25f1c9a6af2256 Mon Sep 17 00:00:00 2001 From: rosch100 Date: Tue, 2 Dec 2025 14:53:55 +0100 Subject: [PATCH 5/6] Add PR description: Multilingual README and description documentation --- PULL_REQUEST.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 PULL_REQUEST.md diff --git a/PULL_REQUEST.md b/PULL_REQUEST.md new file mode 100644 index 00000000..55977ae2 --- /dev/null +++ b/PULL_REQUEST.md @@ -0,0 +1,46 @@ +# Add Multilingual README and Description Documentation + +## Summary + +This PR adds documentation for multilingual README files and repository descriptions in HACS. Repository maintainers can now provide content in multiple languages using standardized file naming patterns. + +## Changes + +1. **README Documentation** (`source/docs/publish/start.md`) + - Added section explaining multilingual README support + - Documents `README.{language_code}.md` naming pattern + - Explains automatic language detection and fallback behavior + +2. **Description Documentation** (`source/docs/publish/start.md`) + - Added section explaining multilingual description support + - Documents `DESCRIPTION.{language_code}.txt` naming pattern + - Explains automatic language detection and fallback to GitHub description + +3. **hacs.json Manifest** (`source/docs/publish/start.md`) + - Updated `content_languages` key documentation + - Clarifies that it applies to both README and description files + - Documents language code requirements (2-letter ISO 639-1) + +4. **User Documentation** (`source/docs/use/repositories/dashboard.md`) + - Added brief note about automatic language detection for README files + +## Related PRs + +- **Backend PR:** https://github.com/hacs/integration/pull/4965 +- **Frontend PR:** https://github.com/hacs/frontend/pull/XXX + +## Checklist + +- [x] Documentation follows project style guidelines +- [x] All examples are correct +- [x] Links are valid +- [x] Content is consistent with implementation + +## Notes + +- Repository maintainers can provide multilingual content using: + - `README.{language_code}.md` for README files + - `DESCRIPTION.{language_code}.txt` for repository descriptions +- HACS automatically displays content matching the user's Home Assistant language setting +- Falls back to default English content if language-specific version is not available + From 9636d31bc2ce257610b57d1cf86e66101712702a Mon Sep 17 00:00:00 2001 From: rosch100 Date: Tue, 2 Dec 2025 15:35:30 +0100 Subject: [PATCH 6/6] docs: Remove multilingual description documentation - Remove section about multilingual repository descriptions - Update content_languages documentation to only mention README files - Update PR description to reflect README-only support --- PULL_REQUEST.md | 22 +++++++--------------- source/docs/publish/start.md | 2 +- 2 files changed, 8 insertions(+), 16 deletions(-) diff --git a/PULL_REQUEST.md b/PULL_REQUEST.md index 55977ae2..1271cf25 100644 --- a/PULL_REQUEST.md +++ b/PULL_REQUEST.md @@ -1,8 +1,8 @@ -# Add Multilingual README and Description Documentation +# Add Multilingual README Documentation ## Summary -This PR adds documentation for multilingual README files and repository descriptions in HACS. Repository maintainers can now provide content in multiple languages using standardized file naming patterns. +This PR adds documentation for multilingual README files in HACS. Repository maintainers can now provide README content in multiple languages using standardized file naming patterns. ## Changes @@ -11,17 +11,11 @@ This PR adds documentation for multilingual README files and repository descript - Documents `README.{language_code}.md` naming pattern - Explains automatic language detection and fallback behavior -2. **Description Documentation** (`source/docs/publish/start.md`) - - Added section explaining multilingual description support - - Documents `DESCRIPTION.{language_code}.txt` naming pattern - - Explains automatic language detection and fallback to GitHub description - -3. **hacs.json Manifest** (`source/docs/publish/start.md`) +2. **hacs.json Manifest** (`source/docs/publish/start.md`) - Updated `content_languages` key documentation - - Clarifies that it applies to both README and description files - Documents language code requirements (2-letter ISO 639-1) -4. **User Documentation** (`source/docs/use/repositories/dashboard.md`) +3. **User Documentation** (`source/docs/use/repositories/dashboard.md`) - Added brief note about automatic language detection for README files ## Related PRs @@ -38,9 +32,7 @@ This PR adds documentation for multilingual README files and repository descript ## Notes -- Repository maintainers can provide multilingual content using: - - `README.{language_code}.md` for README files - - `DESCRIPTION.{language_code}.txt` for repository descriptions -- HACS automatically displays content matching the user's Home Assistant language setting -- Falls back to default English content if language-specific version is not available +- Repository maintainers can provide multilingual README files using `README.{language_code}.md` (e.g., `README.de.md`, `README.fr.md`) +- HACS automatically displays README content matching the user's Home Assistant language setting +- Falls back to default `README.md` if language-specific version is not available diff --git a/source/docs/publish/start.md b/source/docs/publish/start.md index 975d4b75..e68da6f7 100644 --- a/source/docs/publish/start.md +++ b/source/docs/publish/start.md @@ -49,7 +49,7 @@ The following keys are supported: | `homeassistant` | string | No | The minimum required Home Assistant version. | | `hacs` | string | No | The minimum required HACS version. | | `persistent_directory` | string | No | A relative path (within the integration directory) that will be kept safe during upgrades. \_Can only be used with integrations.\* | -| `readme_languages` | list | No | List of supported language codes (e.g., `["de", "fr", "es"]`) for multilingual README files. Language codes must be 2-letter ISO 639-1 codes. | +| `content_languages` | list | No | List of supported language codes (e.g., `["de", "fr", "es"]`) for multilingual README files. Language codes must be 2-letter ISO 639-1 codes. | !!! tip