Merge pull request #13 from pie-framework/develop

Develop

Author: chillenious

.changeset/config.json

@@ -7,5 +7,5 @@
   "access": "public",
   "baseBranch": "master",
   "updateInternalDependencies": "patch",
-  "ignore": ["@acme/likert-scale-plugin", "@pie-qti/qti2-example"]
+  "ignore": ["@acme/likert-scale-plugin", "@pie-qti/qti2-example", "@pie-qti/transform-cli"]
 }

.github/workflows/release.yml

@@ -10,6 +10,7 @@ on:
     paths:
       - ".changeset/**"
       - "packages/**"
+      - "tools/**"
       - "package.json"
       - "bun.lock"
       - "turbo.json"
@@ -89,7 +90,7 @@ jobs:
           after="${{ github.sha }}"
           changed="$(git diff --name-only "$before" "$after" || true)"
 
-          if echo "$changed" | grep -Eq '^packages/[^/]+/(package\.json|CHANGELOG\.md)$'; then
+          if echo "$changed" | grep -Eq '^(packages|tools)/[^/]+/(package\.json|CHANGELOG\.md)$'; then
             echo "has_version_bumps=true" >> "$GITHUB_OUTPUT"
           else
             echo "has_version_bumps=false" >> "$GITHUB_OUTPUT"
@@ -127,8 +128,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          tag_name: ${{ steps.changesets.outputs.publishedPackages[0].version }}
-          release_name: Release ${{ steps.changesets.outputs.publishedPackages[0].version }}
+          # changesets/action outputs `publishedPackages` as a JSON string; parse it before indexing.
+          tag_name: v${{ fromJson(steps.changesets.outputs.publishedPackages)[0].version }}
+          release_name: Release v${{ fromJson(steps.changesets.outputs.publishedPackages)[0].version }}
           body: |
             ## Changes
 

README.md

@@ -80,6 +80,16 @@ Components render via web components (Shadow DOM) with a CSS variable contract:
 
 See [STYLING.md](packages/qti2-default-components/STYLING.md) for the full styling contract.
 
+### Internationalization (i18n)
+
+The player UI supports multiple languages with runtime locale switching:
+
+- **Type-safe translations** — TypeScript autocomplete for all message keys
+- **Runtime switching** — Change language without page reload
+- **Small bundle** — <10 KB gzipped (core + default locale)
+
+See [`@pie-qti/qti2-i18n`](packages/qti2-i18n/) for the complete i18n API and migration guide.
+
 ---
 
 ## Part 2: PIE ↔ QTI Transformation Framework
@@ -183,7 +193,7 @@ bun run preview:pages
 
 - **[Transformation Guide](docs/PIE-QTI-TRANSFORMATION-GUIDE.md)** — Bidirectional transform overview
 - **[Transform App](packages/transform-app/README.md)** — Web UI for transformations
-- **[CLI](packages/cli/README.md)** — Command-line batch operations
+- **[CLI](tools/cli/README.md)** — Command-line batch operations
 - **[QTI → PIE](packages/qti2-to-pie/README.md)** — QTI to PIE transformer
 - **[PIE → QTI](packages/pie-to-qti2/README.md)** — PIE to QTI transformer
 - **[IMS Content Packages](packages/pie-to-qti2/docs/MANIFEST-GENERATION.md)** — Manifest generation

bun.lock

@@ -48,6 +48,7 @@ Everything lives under `packages/`:
 
 ### Optional adapters / supporting packages
 
+- `packages/qti2-i18n`: Internationalization (i18n) system for player UI (type-safe translations, runtime locale switching)
 - `packages/qti2-typeset-katex`: KaTeX typesetting adapter (host-provided `typeset()` function)
 - `packages/qti-processing`: response processing operators/templates used by the item player
 - `packages/qti2-player-elements`, `packages/web-component-loaders`: web-component build/load helpers
@@ -244,6 +245,102 @@ Key references:
 
 ---
 
+## Internationalization (i18n)
+
+> **Status**: Production-ready
+> **Package**: `@pie-qti/qti2-i18n`
+
+### Overview
+
+The PIE-QTI player includes a lightweight, type-safe internationalization system for translating player UI strings (buttons, labels, error messages, ARIA text, etc.).
+
+**Note**: This system translates the **player interface**, not QTI assessment content. Assessments are authored in the content creator's chosen language.
+
+### Key features
+
+- **Type-safe translations**: TypeScript autocomplete for all message keys
+- **Runtime locale switching**: Change language without page reload or component remount
+- **Reactive updates**: Svelte store integration automatically updates all UI text
+- **Web Component compatible**: Works within Shadow DOM boundaries via context API
+- **Small bundle size**: <10 KB gzipped (core + default English locale)
+- **On-demand loading**: Additional locales loaded asynchronously when needed
+
+### Supported locales (Priority 1)
+
+| Locale Code | Language                    |
+|-------------|-----------------------------|
+| `en-US`     | English (United States)     |
+| `es-ES`     | Spanish (Spain)             |
+| `fr-FR`     | French (France)             |
+| `de-DE`     | German (Germany)            |
+| `pt-BR`     | Portuguese (Brazil)         |
+
+### Architecture
+
+The i18n system consists of:
+
+1. **Core I18n class** (`I18n.ts`) - Message lookup, interpolation, pluralization, number/date formatting
+2. **Svelte store integration** (`store.ts`) - Reactive `$t`, `$formatNumber`, `$formatDate` stores
+3. **Context API** (`context.ts`) - Pass i18n instance through component tree (including Shadow DOM)
+4. **Locale files** (`locales/*.ts`) - TypeScript modules with structured translation messages
+5. **LocaleSwitcher component** - Dropdown UI for runtime locale selection
+
+### Usage in components
+
+```svelte
+<script lang="ts">
+  import { t } from '@pie-qti/qti2-i18n';
+</script>
+
+<!-- Simple translation -->
+<button>{$t('common.submit')}</button>
+
+<!-- With interpolation -->
+<p>{$t('assessment.question', { current: 1, total: 10 })}</p>
+
+<!-- Error messages -->
+<div class="alert">{$t('interactions.upload.errorInvalidType', { types: 'pdf, jpg' })}</div>
+```
+
+### Initialization
+
+Initialize i18n in the application root (e.g., `+layout.svelte`):
+
+```typescript
+import { initI18n } from '@pie-qti/qti2-i18n';
+
+const i18n = initI18n('en-US');
+await i18n.loadLocale('en-US');
+```
+
+### Message namespaces
+
+Translations are organized by feature:
+
+- `common.*` - Shared UI text (Submit, Cancel, Next, etc.)
+- `units.*` - Unit formatting (bytes, KB, seconds, etc.)
+- `validation.*` - Form validation messages
+- `interactions.*` - QTI interaction-specific text (organized by interaction type)
+- `assessment.*` - Assessment player UI (navigation, sections, timer, feedback)
+- `accessibility.*` - ARIA labels and screen reader announcements
+
+### Type safety
+
+Message keys are automatically typed from the English locale structure. IDEs provide autocomplete and compile-time validation:
+
+```typescript
+$t('common.submit')  // ✅ Valid
+$t('invalid.key')    // ❌ TypeScript error
+```
+
+### Key references
+
+- `packages/qti2-i18n/README.md` - Full API documentation and migration guide
+- `docs/i18n-design-plan.md` - Detailed design document with architecture rationale
+- `packages/qti2-i18n/src/locales/en-US.ts` - Complete list of available translation keys
+
+---
+
 ## Transformations: QTI ↔ PIE
 
 > **Status**: Under active development

docs/ARCHITECTURE.md

@@ -72,7 +72,7 @@ Comprehensive architecture and implementation plan for the QTI Batch Processor w
 
 - **Getting Started:** See main [README.md](../README.md) in repo root
 - **Web App Development:** Follow BATCH_PROCESSOR_ARCHITECTURE.md phases
-- **CLI Tools:** See `packages/cli/README.md`
+- **CLI Tools:** See `tools/cli/README.md`
 
 ### Specs (local snapshots for fast search / LLM use)