Skip to content

Add documentation for multilingual README support and complete hacs.json keys #660

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
rosch100 wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Add documentation for multilingual README support and complete hacs.json keys #660

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f60e824
Add documentation for multilingual README support and complete hacs.j…
Dec 2, 2025
78fdf90
Fix grammar: complete sentence in country field description
Dec 2, 2025
700b3b6
Rename supported_languages to readme_languages and remove validation …
Dec 2, 2025
9a93f2d
Remove render_readme and revert country to string per review feedback
Dec 2, 2025
8b475a6
Add PR description: Multilingual README and description documentation
Dec 2, 2025
9636d31
docs: Remove multilingual description documentation
Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions source/docs/publish/start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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._
Expand All @@ -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. 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.\* |
| `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
Expand Down
1 change: 1 addition & 0 deletions source/docs/use/repositories/dashboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down