docs: add multi-language output guide

Document how to configure OpenSpec to generate artifacts in languages other than English using the existing context field in config.yaml. Includes examples for Portuguese, Spanish, Chinese, Japanese, French, and German, plus tips for handling technical terminology.
fix(ci): use workflow_dispatch for polish release notes (#533 )
2026-10-14 05:19:53 +08:00 · 2026-01-20 00:55:26 -08:00 · 2026-01-20 00:36:24 -08:00 · 2026-01-20 00:09:49 -08:00
4 changed files with 255 additions and 24 deletions
@@ -1,14 +1,8 @@
 name: Polish Release Notes

-# Automatically polish release notes when a release is published.
-# Also supports manual trigger as a fallback.
-#
-# Note: The Claude Code Action works with any GitHub event when using the
-# `prompt` parameter for custom automations. If release triggers stop working,
-# check https://github.com/anthropics/claude-code-action for updates.
+# Uses Claude to transform raw changelog into polished release notes.
+# Triggered automatically by release-prepare after publishing, or manually.
 on:
-  release:
-    types: [published]
  workflow_dispatch:
    inputs:
      tag_name:
@@ -17,7 +11,7 @@ on:
        type: string

 env:
-  TAG_NAME: ${{ github.event.release.tag_name || inputs.tag_name }}
+  TAG_NAME: ${{ inputs.tag_name }}

 permissions:
  contents: write
@@ -47,6 +47,7 @@ jobs:

      # Opens/updates the Version Packages PR; publishes when the Version PR merges
      - name: Create/Update Version PR
+        id: changesets
        uses: changesets/action@v1
        with:
          title: 'chore(release): version packages'
@@ -57,3 +58,14 @@ jobs:
        env:
          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
          # npm authentication handled via OIDC trusted publishing (no token needed)
+
+      # Trigger release notes polishing after a release is published
+      - name: Polish release notes
+        if: steps.changesets.outputs.published == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          # Get version from package.json (just bumped by changesets)
+          TAG="v$(jq -r .version package.json)"
+          echo "Triggering polish workflow for $TAG"
+          gh workflow run polish-release-notes.yml -f tag_name="$TAG"
@@ -4,15 +4,15 @@

 ### Minor Changes

- [#530](https://github.com/Fission-AI/OpenSpec/pull/530) [`33466b1`](https://github.com/Fission-AI/OpenSpec/commit/33466b1e2a6798bdd6d0e19149173585b0612e6f) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+- [#530](https://github.com/Fission-AI/OpenSpec/pull/530) [`33466b1`](https://github.com/Fission-AI/OpenSpec/commit/33466b1e2a6798bdd6d0e19149173585b0612e6f) Thanks [@TabishB](https://github.com/TabishB)! - Add project-level configuration, project-local schemas, and schema management commands
+
+  **New Features**

  - **Project-level configuration** — Configure OpenSpec behavior per-project via `openspec/config.yaml`, including custom rules injection, context files, and schema resolution settings
-
  - **Project-local schemas** — Define custom artifact schemas within your project's `openspec/schemas/` directory for project-specific workflows
-
  - **Schema management commands** — New `openspec schema` commands (`list`, `show`, `export`, `validate`) for inspecting and managing artifact schemas (experimental)

-  ### Bug Fixes
+  **Bug Fixes**

  - Fixed config loading to handle null `rules` field in project configuration

@@ -20,16 +20,18 @@

 ### Minor Changes

- [#516](https://github.com/Fission-AI/OpenSpec/pull/516) [`b5a8847`](https://github.com/Fission-AI/OpenSpec/commit/b5a884748be6156a7bb140b4941cfec4f20a9fc8) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+- [#516](https://github.com/Fission-AI/OpenSpec/pull/516) [`b5a8847`](https://github.com/Fission-AI/OpenSpec/commit/b5a884748be6156a7bb140b4941cfec4f20a9fc8) Thanks [@TabishB](https://github.com/TabishB)! - Add feedback command and Nix flake support
+
+  **New Features**

  - **Feedback command** — Submit feedback directly from the CLI with `openspec feedback`, which creates GitHub Issues with automatic metadata inclusion and graceful fallback for manual submission
  - **Nix flake support** — Install and develop openspec using Nix with the new `flake.nix`, including automated flake maintenance and CI validation

-  ### Bug Fixes
+  **Bug Fixes**

  - **Explore mode guardrails** — Explore mode now explicitly prevents implementation, keeping the focus on thinking and discovery while still allowing artifact creation

-  ### Other
+  **Other**

  - Improved change inference in `opsx apply` — automatically detects the target change from conversation context or prompts when ambiguous
  - Streamlined archive sync assessment with clearer delta spec location guidance
@@ -38,11 +40,13 @@

 ### Minor Changes

- [#502](https://github.com/Fission-AI/OpenSpec/pull/502) [`9db74aa`](https://github.com/Fission-AI/OpenSpec/commit/9db74aa5ac6547efadaed795217cfa17444f2004) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+- [#502](https://github.com/Fission-AI/OpenSpec/pull/502) [`9db74aa`](https://github.com/Fission-AI/OpenSpec/commit/9db74aa5ac6547efadaed795217cfa17444f2004) Thanks [@TabishB](https://github.com/TabishB)! - Add `/opsx:verify` command and fix vitest process storms
+
+  **New Features**

  - **`/opsx:verify` command** — Validate that change implementations match their specifications

-  ### Bug Fixes
+  **Bug Fixes**

  - Fixed vitest process storms by capping worker parallelism
  - Fixed agent workflows to use non-interactive mode for validation commands
@@ -52,19 +56,21 @@

 ### Minor Changes

- eb152eb: ### New Features
+- eb152eb: Add Continue IDE support, shell completions, and `/opsx:explore` command
+
+  **New Features**

  - **Continue IDE support** – OpenSpec now generates slash commands for [Continue](https://continue.dev/), expanding editor integration options alongside Cursor, Windsurf, Claude Code, and others
  - **Shell completions for Bash, Fish, and PowerShell** – Run `openspec completion install` to set up tab completion in your preferred shell
  - **`/opsx:explore` command** – A new thinking partner mode for exploring ideas and investigating problems before committing to changes
  - **Codebuddy slash command improvements** – Updated frontmatter format for better compatibility

-  ### Bug Fixes
+  **Bug Fixes**

  - Shell completions now correctly offer parent-level flags (like `--help`) when a command has subcommands
  - Fixed Windows compatibility issues in tests

-  ### Other
+  **Other**

  - Added optional anonymous usage statistics to help understand how OpenSpec is used. This is **opt-out** by default – set `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable. Only command names and version are collected; no arguments, file paths, or content. Automatically disabled in CI environments.

@@ -119,13 +125,15 @@

 ### Minor Changes

- 2e71835: ### New Features
+- 2e71835: Add `openspec config` command and Oh-my-zsh completions
+
+  **New Features**

  - Add `openspec config` command for managing global configuration settings
  - Implement global config directory with XDG Base Directory specification support
  - Add Oh-my-zsh shell completions support for enhanced CLI experience

-  ### Bug Fixes
+  **Bug Fixes**

  - Fix hang in pre-commit hooks by using dynamic imports
  - Respect XDG_CONFIG_HOME environment variable on all platforms
@@ -133,7 +141,7 @@
  - Align cli-completion spec with implementation
  - Remove hardcoded agent field from slash commands

-  ### Documentation
+  **Documentation**

  - Alphabetize AI tools list in README and make it collapsible

@@ -0,0 +1,217 @@
+# Multi-Language Output Guide
+
+Configure OpenSpec to generate artifacts in languages other than English.
+
+## Overview
+
+OpenSpec can output proposals, specs, designs, and tasks in any language by adding language instructions to your project's `context` configuration. This approach uses the existing config system without requiring any code changes.
+
+## Quick Setup
+
+### If you already have a config file
+
+Add a language instruction to your existing `openspec/config.yaml`:
+
+```yaml
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+  Use Portuguese technical terminology where appropriate.
+
+  # Your other project context below...
+  Tech stack: TypeScript, React, Node.js
+```
+
+That's it. All generated artifacts will now be in Portuguese.
+
+### If you don't have a config file yet
+
+You can create one interactively or manually:
+
+**Option 1: Interactive setup**
+
+```bash
+openspec artifact-experimental-setup
+```
+
+This will guide you through creating `openspec/config.yaml` with schema selection, context, and rules.
+
+**Option 2: Manual creation**
+
+Create the file `openspec/config.yaml` in your project root:
+
+```bash
+mkdir -p openspec
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+EOF
+```
+
+## Language Examples
+
+### Portuguese (Brazil)
+
+```yaml
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts (proposals, specs, designs, tasks) must be written in Brazilian Portuguese.
+  Use Brazilian Portuguese conventions for technical terminology.
+```
+
+### Spanish
+
+```yaml
+context: |
+  Idioma: Español
+  Todos los artefactos deben escribirse en español.
+  Utilizar terminología técnica en español cuando sea posible.
+```
+
+### Chinese (Simplified)
+
+```yaml
+context: |
+  语言：中文（简体）
+  所有产出物（提案、规格、设计、任务）必须用简体中文撰写。
+  技术术语可以保留英文原文，但说明应使用中文。
+```
+
+### Japanese
+
+```yaml
+context: |
+  言語：日本語
+  すべての成果物は日本語で作成してください。
+  技術用語は必要に応じて英語を併記可能です。
+```
+
+### French
+
+```yaml
+context: |
+  Langue : Français
+  Tous les artefacts doivent être rédigés en français.
+  Utiliser la terminologie technique française lorsque possible.
+```
+
+### German
+
+```yaml
+context: |
+  Sprache: Deutsch
+  Alle Artefakte müssen auf Deutsch verfasst werden.
+  Technische Fachbegriffe können auf Englisch beibehalten werden.
+```
+
+## How It Works
+
+The `context` field in `openspec/config.yaml` is injected into every artifact's instructions as an XML block:
+
+```xml
+<context>
+Language: Portuguese (pt-BR)
+All artifacts must be written in Brazilian Portuguese.
+...
+</context>
+
+<template>
+[Schema's template content]
+</template>
+```
+
+The AI assistant sees this context when generating any artifact and follows the language instruction.
+
+## Tips
+
+### Be Explicit About Scope
+
+Specify which parts should be in the target language:
+
+```yaml
+context: |
+  Language: Spanish
+  Write all prose, descriptions, and explanations in Spanish.
+  Code comments may remain in English for consistency with the codebase.
+  Variable names and code identifiers should stay in English.
+```
+
+### Handle Technical Terms
+
+Decide how to handle technical terminology:
+
+```yaml
+context: |
+  Language: Japanese
+  Write in Japanese, but:
+  - Keep technical terms like "API", "REST", "GraphQL" in English
+  - Provide Japanese explanations in parentheses for complex terms on first use
+  - Code examples and file paths remain in English
+```
+
+### Combine with Other Context
+
+Language settings work alongside your other project context:
+
+```yaml
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+
+  Tech stack: TypeScript, React 18, Node.js 20
+  Database: PostgreSQL with Prisma ORM
+  Testing: Vitest + React Testing Library
+
+  Conventions:
+  - Use functional components with hooks
+  - Follow existing patterns in src/components/
+```
+
+## Verification
+
+To verify your language config is working:
+
+```bash
+# Create a test change
+openspec new change test-language
+
+# Check the instructions - should show your language context
+openspec instructions proposal --change test-language
+
+# Output will include:
+# <context>
+# Language: Portuguese (pt-BR)
+# All artifacts must be written in Brazilian Portuguese.
+# ...
+# </context>
+```
+
+## Limitations
+
+- Language instructions apply to **all** artifacts. You cannot set different languages for different artifact types.
+- The effectiveness depends on the AI model's proficiency in the target language.
+- Technical diagrams, code samples, and file paths typically remain in English regardless of language setting.
+
+## Future Considerations
+
+We're considering adding a dedicated `language` field to the config schema in a future release:
+
+```yaml
+# Potential future syntax (not yet implemented)
+schema: spec-driven
+language: pt-BR
+```
+
+For now, the `context` approach described above is the recommended method. It provides full flexibility and works with all current versions of OpenSpec.
+
+## Related Documentation
+
+- [Project Config Demo](./project-config-demo.md) - Overview of project configuration
+- [Experimental Workflow Guide](./experimental-workflow.md) - Full workflow documentation