-
Notifications
You must be signed in to change notification settings - Fork 0
π Native i18n: Runtime multi-language support (Spanish + English) #15
Description
π Feature: Native i18n β Multi-language Artifact Generation
Context
The docs/LANGUAGE_POLICY.md document establishes the rule: the repository stays in English, but the user-facing artifact experience should match the user's language. Currently this is handled reactively β the tool detects user language and generates in that language, but this behavior is not systematic, not verified, and not controllable.
A proper i18n system makes language a first-class runtime feature: detect, generate, verify, and allow the user to override. This enables the tool to be used by bilingual teams, international stakeholders, and in contexts where the artifact language matters more than the tool's language.
Problem
- Language is currently handled inconsistently β some artifacts respect user language, others default to English
- There is no way to specify a target artifact language as a parameter (e.g.,
--lang es) - The artifact's
<html lang="en">is never updated to reflect the generated content language - Language detection is implicit, not configurable or overridable
What This Resolves
- Runtime
--langflag ondeliver-artifact.pyto specify target language - Automatic language detection using the first message language
<html lang="...">attribute is set correctly based on generated content language- Content generation in both Spanish and English as first-class modes, with structured approach for adding more languages
- i18n verification in
audit-artifact.pythat checks thelangattribute and flags mismatches
Proposed Approach
Language detection utility (scripts/i18n-detect.py): a standalone module that takes text input and returns the detected language code (en/es). Uses character frequency analysis with Spanish-specific markers (accents, common words).
CLI integration:
deliver-artifact.py --lang esforces Spanish outputdeliver-artifact.py --lang enforces English outputdeliver-artifact.py(no flag) detects language automatically from message content
Artifact language metadata: Every delivered artifact records its language in JSON metadata:
{
"artifact_language": "es",
"user_language_hint": "en",
"language_detection_method": "content_analysis"
}Core phrase translations (scripts/i18n-phrases.json): a lightweight translation layer for at least 20 structural artifact elements. Covers: best_next_move, what_i_checked, recommendation, next_action, save_decision, copy_prompt, evidence, risks, recommendation_label, status, pattern, artifact_type, and more.
Validation in audit-artifact.py: check that <html lang> attribute is present and consistent with the generated content. Flag missing or mismatched lang attributes as a quality issue.
Acceptance Criteria
deliver-artifact.py --lang esgenerates artifact with<html lang="es">deliver-artifact.py --lang engenerates artifact with<html lang="en">deliver-artifact.py(no flag) detects language automatically from message content- Key structural phrases in
i18n-phrases.jsonare available in bothenandes audit-artifact.pyvalidates that<html lang>attribute is present and consistent- Artifact metadata JSON includes
artifact_languagefield i18n-phrases.jsoncovers at least 20 key structural phrasesvalidate-runtime.shincludes i18n smoke test (generate en artifact, generate es artifact, verify lang attributes differ)- Bilingual artifacts (user speaks Spanish, artifact audience is English) handled correctly per LANGUAGE_POLICY.md
Quality Verification
Run the i18n smoke test to verify language detection, badge rendering, and metadata accuracy for both English and Spanish artifacts.
Labels
enhancement, internationalization, i18n, runtime
Milestone
v1.1 β Collaboration-ready artifacts