openspec(add-french-translation): propose artifacts
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-07
|
||||
@@ -0,0 +1,35 @@
|
||||
## Context
|
||||
|
||||
PR #14 is one commit, `704f55e` by aurel <aurelien.ruat@hotmail.fr>, whose parent is the current `master` head (`851ec3a`). GitHub reports it mergeable with no conflicts. Checked before this change:
|
||||
|
||||
- `fr.json` has exactly the key set of `strings.json` and `en.json`, which also match each other.
|
||||
- Every `{reason}` placeholder and the README link in the token step are carried over.
|
||||
- The full suite passes on the PR branch: 77 tests, 587 subtests, including the new `test_translations.py`.
|
||||
|
||||
`git fetch github pull/14/head` makes the commit available locally.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Ship the contribution byte-for-byte, with aurel as the commit author, and have GitHub show PR #14 as merged.
|
||||
|
||||
**Non-Goals:**
|
||||
- Editing the French wording or the contributed test (style, unittest vs pytest, hardcoded `("en", "fr")`).
|
||||
|
||||
## Decisions
|
||||
|
||||
**Merge the original commit, not a squash or a re-applied diff.** The worktree branch `agent/add-french-translation` starts at `master` and fast-forwards to `704f55e`; the version bump is a separate maintainer commit on top. When the branch is later merged into `master` and pushed to `github`, `704f55e` is reachable from the PR's base branch, so GitHub marks PR #14 merged and attributes the commit to aurel. Squashing or cherry-picking would change the hash, lose that link, and need a manual PR close.
|
||||
|
||||
**Integration-only patch release (0.4.6).** The card has no translation files, so it is unchanged. The versioning rule in `PROJECT_HYGIENE.md` allows a diverging patch.
|
||||
|
||||
**Keep the test strict.** Home Assistant falls back to English for missing keys, so partial translations would work at runtime. The maintainer chose exact parity instead, so French never falls silently behind. The cost is one more file to touch per string change, recorded in `PROJECT_HYGIENE.md`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [A future agent adds a string to `strings.json` and `en.json` only] → The test fails in that change; the `PROJECT_HYGIENE.md` note tells the agent to write the French entry rather than relax the test.
|
||||
- [The new strings are shown on a narrow UI and truncate] → Not seen in testing, and the contributor runs it live. Fix in a follow-up only if a user reports it.
|
||||
- [No on-device check on the dev host] → As with 0.4.4 and 0.4.5, there is no Home Assistant on the dev host. The contributor's own instance is the live check; the static checks above cover the files.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
None. Updating via HACS and restarting Home Assistant picks up `fr.json`. Rollback is reinstalling 0.4.5.
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
[PR #14](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/pull/14) from @Aurel004 (aurel) adds a complete French translation, so French-language Home Assistant installs show the config flow, errors and entity names in French instead of English. The contributor runs it on his own instance and checked the AI-generated strings by hand; the maintainer had a native French speaker look at it too. It is a first contribution, so it ships exactly as submitted, with his authorship kept.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Merge the PR's single commit (`704f55e`, authored by aurel) unchanged. It adds:
|
||||
- `custom_components/perfectdraft/translations/fr.json`, covering every key in `strings.json`.
|
||||
- `tests/test_translations.py`, which fails when `en.json` or `fr.json` has a different key structure from `strings.json`.
|
||||
- No wording edits. "Marquer le fût changé" stays as submitted; it is correct, and shorter text suits the button label.
|
||||
- Bump the integration to 0.4.6. The card has no translations and stays at 0.4.5, which the versioning rule allows (shared major.minor, patch may diverge).
|
||||
- Record in `PROJECT_HYGIENE.md` that from now on every new or renamed UI string needs an English and a French entry, because the new test enforces exact key parity.
|
||||
- Release v0.4.6 crediting @Aurel004.
|
||||
|
||||
Not in scope:
|
||||
|
||||
- Translated entity states or attributes. `strings.json` defines none, so there is nothing to translate.
|
||||
- Other languages, or loosening the parity test to allow partial translations.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
None.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `hacs-packaging`: the "Translations" requirement covers English only. It now also requires a French translation and exact key parity between `strings.json` and every shipped translation file.
|
||||
|
||||
## Impact
|
||||
|
||||
- Users with Home Assistant set to French see French labels after updating. Existing entity IDs are kept in the entity registry and don't change; only display names do. Everyone else is unaffected.
|
||||
- Contributors and agents: any change to `strings.json` must update `translations/en.json` and `translations/fr.json` in the same commit, or `tests/test_translations.py` fails.
|
||||
- Files: `custom_components/perfectdraft/translations/fr.json` (new), `tests/test_translations.py` (new), `custom_components/perfectdraft/manifest.json` (version), `PROJECT_HYGIENE.md` (main checkout).
|
||||
@@ -0,0 +1,19 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Translations
|
||||
The integration SHALL provide English and French UI strings for all config flow steps, errors, abort reasons, options, and entity names. Every shipped translation file SHALL have exactly the same key structure as `strings.json`.
|
||||
|
||||
#### Scenario: Translation files
|
||||
- **WHEN** HA renders the integration UI
|
||||
- **THEN** `strings.json` and `translations/en.json` SHALL provide labels for all steps, fields, errors, and entity names
|
||||
- **THEN** descriptions SHALL not contain curly braces (parsed as translation placeholders) or newlines (cause MALFORMED_ARGUMENT)
|
||||
|
||||
#### Scenario: French UI
|
||||
- **WHEN** HA renders the integration UI with its language set to French
|
||||
- **THEN** `translations/fr.json` SHALL provide French labels for all steps, fields, errors, abort reasons, options, and entity names
|
||||
- **THEN** each French string SHALL use the same `{placeholder}` names as its English counterpart
|
||||
|
||||
#### Scenario: Key parity
|
||||
- **WHEN** a key is added to, renamed in, or removed from `strings.json`
|
||||
- **THEN** `translations/en.json` and `translations/fr.json` SHALL be updated to the same key structure in the same change
|
||||
- **THEN** the test suite SHALL fail if any of the three files has a key the others lack
|
||||
@@ -0,0 +1,20 @@
|
||||
## 1. Worktree and contribution
|
||||
|
||||
- [ ] 1.1 `scripts/agent-worktree.sh create add-french-translation`; verify `.worktree/add-french-translation/.agent-lock` exists and `git worktree list` shows branch `agent/add-french-translation` at `master`
|
||||
- [ ] 1.2 `git fetch github pull/14/head`, then in the worktree `git merge --ff-only 704f55e5958717899fea2265f1a3c627dd4cde9d`; verify `git log -1 --format='%H %an'` shows `704f55e…` by aurel and `git diff master --stat` lists only `translations/fr.json` and `tests/test_translations.py`
|
||||
- [ ] 1.3 Verify the contribution against the spec: `fr.json` key set equals `strings.json`, and every string uses the same `{placeholder}` names as `strings.json`; then `../../.venv-test/bin/pytest tests/` from the worktree passes, including `test_translations.py`
|
||||
|
||||
## 2. Version
|
||||
|
||||
- [ ] 2.1 Bump `custom_components/perfectdraft/manifest.json` to 0.4.6 and commit as the maintainer; verify `git diff HEAD~1` is the single version line and the full suite still passes. Record the commit hash here
|
||||
|
||||
## 3. Project hygiene
|
||||
|
||||
- [ ] 3.1 Add a line to `PROJECT_HYGIENE.md` section 11 (main checkout): every new, renamed or removed key in `strings.json` must be mirrored in `translations/en.json` and `translations/fr.json` in the same commit, with a French string written rather than an English placeholder or a relaxed test; `tests/test_translations.py` enforces it. Commit in the main checkout; verify with `git log -1 -- PROJECT_HYGIENE.md`
|
||||
|
||||
## Workflow follow-up
|
||||
|
||||
- Archive per `AGENTS.md`: merge `agent/add-french-translation` into `master` with `--no-ff` (keeps `704f55e` intact), push `master` to `origin` and `github`, sync the `hacs-packaging` delta into `openspec/specs/`, archive, remove the worktree and branch.
|
||||
- After the push, confirm via the GitHub API that PR #14 reports `merged: true`. If it doesn't, close it with a comment linking the merge commit.
|
||||
- Tag `v0.4.6` and publish the GitHub release "v0.4.6 — French translation" in the format of v0.4.5: French UI for setup, errors and entity names; thanks to @Aurel004 for [#14](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/pull/14); note that the card stays at 0.4.5, no breaking changes, no re-configuration.
|
||||
- Comment on PR #14 with a thank-you and the release link.
|
||||
Reference in New Issue
Block a user