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

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
+

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

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.