diff --git a/PULL_REQUEST.md b/PULL_REQUEST.md new file mode 100644 index 00000000..1271cf25 --- /dev/null +++ b/PULL_REQUEST.md @@ -0,0 +1,38 @@ +# Add Multilingual README Documentation + +## Summary + +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 + +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. **hacs.json Manifest** (`source/docs/publish/start.md`) + - Updated `content_languages` key documentation + - Documents language code requirements (2-letter ISO 639-1) + +3. **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 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 0cb22424..e68da6f7 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,14 @@ 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) | | `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.\* | +| `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 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.