WinterCMS research

2026-02-18 01:31:41 +01:00
parent bec00a8bd5
commit 29766aee93
40 changed files with 8529 additions and 0 deletions
--- a/docs/research/wintercms/queststream-14-i18n/14-01-PLAN.md
+++ b/docs/research/wintercms/queststream-14-i18n/14-01-PLAN.md
@@ -0,0 +1,269 @@
+---
+phase: 14-translation-polish-testing
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - vue-queststream-app/package.json
+  - vue-queststream-app/vitest.config.ts
+  - vue-queststream-app/scripts/i18n-coverage.ts
+  - vue-queststream-app/tests/i18n/polish-pluralization.test.ts
+  - .planning/phases/14-translation-polish-testing/14-TRANSLATION-REVIEW.md
+autonomous: true
+
+must_haves:
+  truths:
+    - "Coverage script identifies strings where PL value equals EN value (untranslated)"
+    - "Vitest runs Polish pluralization tests with all critical test values (0, 1, 2, 5, 11, 21, 22, 100)"
+    - "All plural keys have correct form count in both EN and PL files (4 forms for Polish)"
+    - "Translation review file contains side-by-side EN|PL comparison for all strings"
+  artifacts:
+    - path: "vue-queststream-app/scripts/i18n-coverage.ts"
+      provides: "Coverage report script that compares en.json vs pl.json"
+      min_lines: 50
+    - path: "vue-queststream-app/vitest.config.ts"
+      provides: "Vitest configuration for unit tests"
+      contains: "defineConfig"
+    - path: "vue-queststream-app/tests/i18n/polish-pluralization.test.ts"
+      provides: "Unit tests for Polish 4-form pluralization"
+      contains: "describe"
+    - path: ".planning/phases/14-translation-polish-testing/14-TRANSLATION-REVIEW.md"
+      provides: "Side-by-side translation review document"
+      min_lines: 100
+  key_links:
+    - from: "vue-queststream-app/scripts/i18n-coverage.ts"
+      to: "vue-queststream-app/i18n/locales/en.json"
+      via: "JSON import"
+      pattern: "locales/en.json"
+    - from: "vue-queststream-app/tests/i18n/polish-pluralization.test.ts"
+      to: "vue-queststream-app/i18n/i18n.config.ts"
+      via: "Same pluralization logic"
+      pattern: "plPluralRule"
+---
+
+<objective>
+Create translation coverage tooling and generate comprehensive review file for Polish translations.
+
+Purpose: Establish automated verification of translation coverage and prepare side-by-side review document for user to audit Polish translations before final polish phase.
+
+Output:
+- i18n-coverage.ts script that reports untranslated strings and plural form mismatches
+- Vitest configured and running pluralization unit tests
+- Side-by-side markdown review file of all 1858 translation keys
+</objective>
+
+<execution_context>
+@/home/golem/.claude/get-shit-done/workflows/execute-plan.md
+@/home/golem/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/14-translation-polish-testing/14-CONTEXT.md
+@.planning/phases/14-translation-polish-testing/14-RESEARCH.md
+@vue-queststream-app/i18n/i18n.config.ts
+@vue-queststream-app/package.json
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Install Vitest and create coverage script</name>
+  <files>
+    vue-queststream-app/package.json
+    vue-queststream-app/vitest.config.ts
+    vue-queststream-app/scripts/i18n-coverage.ts
+  </files>
+  <action>
+1. Install Vitest as dev dependency:
+   ```bash
+   cd vue-queststream-app && pnpm add -D vitest
+   ```
+
+2. Create vitest.config.ts with minimal configuration:
+   ```typescript
+   import { defineConfig } from 'vitest/config'
+
+   export default defineConfig({
+     test: {
+       include: ['tests/**/*.{test,spec}.ts'],
+       environment: 'node',
+     },
+   })
+   ```
+
+3. Add test script to package.json scripts:
+   ```json
+   "test": "vitest run",
+   "test:watch": "vitest"
+   ```
+
+4. Create scripts/i18n-coverage.ts following RESEARCH.md pattern:
+   - Load en.json and pl.json using fs.readFileSync
+   - Define EXCLUSIONS array for intentionally-same strings (QuestStream, XP, PIN, OK, etc.)
+   - Find keys where EN value === PL value (excluding plurals and exclusions)
+   - Find plural keys with form count mismatch (EN has 2 forms, PL needs 4)
+   - Output report with totals and lists
+   - Exit code 1 if critical issues found (missing in PL, plural mismatch)
+   - Run with: npx tsx scripts/i18n-coverage.ts
+  </action>
+  <verify>
+    Run `cd vue-queststream-app && npx tsx scripts/i18n-coverage.ts` - should output coverage report without error
+    Run `cd vue-queststream-app && pnpm test` - should find 0 tests initially (vitest configured correctly)
+  </verify>
+  <done>
+    Coverage script runs and reports any untranslated strings
+    Vitest is installed and configured
+    package.json has test scripts
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create Polish pluralization unit tests</name>
+  <files>
+    vue-queststream-app/tests/i18n/polish-pluralization.test.ts
+  </files>
+  <action>
+1. Create tests/i18n/ directory
+
+2. Create polish-pluralization.test.ts with comprehensive tests:
+   - Extract the plPluralRule function from i18n.config.ts (copy the logic)
+   - Test all critical values from RESEARCH.md:
+     - Zero form (0)
+     - One form (1, 21, 31, 101)
+     - Few form (2, 3, 4, 22, 23, 24, 102, 103, 104)
+     - Many form (0, 5, 10, 11, 12, 13, 14, 15, 19, 20, 25, 100, 105, 111, 112)
+   - Use describe/it pattern from vitest
+   - Include test for 3-form strings (where choicesLength < 4)
+
+3. Test structure:
+   ```typescript
+   import { describe, it, expect } from 'vitest'
+
+   // Copy exact pluralization function from i18n.config.ts
+   function plPluralRule(choice: number, choicesLength: number): number {
+     // ... exact implementation
+   }
+
+   describe('Polish pluralization rules', () => {
+     describe('4-form strings (zero|one|few|many)', () => {
+       const testCases = [
+         { n: 0, expected: 0, description: 'zero' },
+         { n: 1, expected: 1, description: 'one' },
+         // ... all test cases
+       ]
+
+       testCases.forEach(({ n, expected, description }) => {
+         it(`returns index ${expected} for n=${n} (${description})`, () => {
+           expect(plPluralRule(n, 4)).toBe(expected)
+         })
+       })
+     })
+
+     describe('3-form fallback strings', () => {
+       it('uses index 2 for "many" when only 3 forms available', () => {
+         expect(plPluralRule(5, 3)).toBe(2)
+       })
+     })
+   })
+   ```
+  </action>
+  <verify>
+    Run `cd vue-queststream-app && pnpm test` - all pluralization tests should pass
+    Check tests/i18n/polish-pluralization.test.ts exists with 20+ test cases
+  </verify>
+  <done>
+    Polish pluralization tests pass
+    Tests cover all critical values (0, 1, 2, 3, 4, 5, 11, 12, 21, 22, 100, 101, 102, 105)
+    Both 4-form and 3-form scenarios tested
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Generate translation review file</name>
+  <files>
+    .planning/phases/14-translation-polish-testing/14-TRANSLATION-REVIEW.md
+  </files>
+  <action>
+1. Create a script or use Node directly to generate review markdown:
+   - Read both en.json and pl.json
+   - For each key, output: | English | Polish | Context |
+   - Group by domain (auth, parent, child, quest, settings, etc.) based on key patterns
+   - For plural strings, expand to show all forms separately
+   - Flag potentially untranslated strings with "CHECK" marker
+
+2. Generate 14-TRANSLATION-REVIEW.md with structure:
+   ```markdown
+   # Translation Review: QuestStream EN → PL
+
+   Generated: [date]
+   Total keys: 1858
+   Potentially untranslated: [count]
+
+   ## Instructions for Review
+   - Edit Polish values inline where corrections needed
+   - Add context hints where ambiguous
+   - Mark approved translations with ✓
+
+   ## Auth & Navigation
+   | English | Polish | Status |
+   |---------|--------|--------|
+   | Login | Zaloguj się | ✓ |
+   | ... | ... | ... |
+
+   ## Parent Dashboard
+   ...
+
+   ## Child Dashboard
+   ...
+
+   ## Pluralization (requires 4 forms)
+   | Key | EN | PL (one|few|many|other) | Status |
+   ...
+   ```
+
+3. Include coverage report summary at the top showing any issues found
+  </action>
+  <verify>
+    Check .planning/phases/14-translation-polish-testing/14-TRANSLATION-REVIEW.md exists
+    File should contain all 1858 translation keys in tabular format
+    Plural strings should show expanded forms
+  </verify>
+  <done>
+    Review file generated with all translations in side-by-side format
+    Plural strings expanded to show all forms
+    Potentially untranslated strings flagged
+    File ready for user review
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. Run coverage script: `cd vue-queststream-app && npx tsx scripts/i18n-coverage.ts`
+   - Should output total keys, potentially untranslated count
+   - Should identify any plural form mismatches
+
+2. Run unit tests: `cd vue-queststream-app && pnpm test`
+   - All 20+ pluralization tests should pass
+
+3. Check review file: `.planning/phases/14-translation-polish-testing/14-TRANSLATION-REVIEW.md`
+   - Should contain 1858 translation entries
+   - Should be organized by domain
+   - Plural strings should show all forms
+</verification>
+
+<success_criteria>
+- Coverage script identifies untranslated strings (if any)
+- Vitest configured and running with 20+ passing tests
+- Polish pluralization rules tested comprehensively (0, 1, 2, 5, 11, 21, 22, 100, 101, 105)
+- Translation review markdown generated for user audit
+- No plural form count mismatches between en.json and pl.json
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-translation-polish-testing/14-01-SUMMARY.md`
+</output>