Go CLI i18n

Overview

This skill documents the Go CLI i18n rules used in this repo, including language detection, locale files, and key naming conventions.

When to Use

• •You add or edit any user-facing CLI string in cmd/skills-x
• •You need to add a new skill description for list output
• •You are troubleshooting mixed language output or missing translations

Architecture Snapshot

• •i18n runtime: cmd/skills-x/i18n/i18n.go
• •Locale files: cmd/skills-x/i18n/locales/zh.yaml, cmd/skills-x/i18n/locales/en.yaml
• •Embed: //go:embed locales/*.yaml (locales are embedded at build time)

Language Selection

Priority order in detectLanguage():

1. •SKILLS_LANG
2. •LANG
3. •LC_ALL
4. •Default: zh

Normalization uses prefix matching:

• •zh, zh_CN, zh_TW → zh
• •en, en_US → en
• •Unsupported → zh

Using i18n in Go

Initialize once (early in main):

import "github.com/castle-x/skills-x/cmd/skills-x/i18n"

i18n.MustInit()

Translate strings:

title := i18n.T("list_header")
msg := i18n.Tf("init_success", skillName)

Missing keys return the key itself (useful for spotting gaps).

Key Naming Conventions

Use lowercase + underscores with category prefixes:

• •app_ app metadata
• •cmd_ command descriptions/flags
• •list_ list output
• •init_ init output
• •err_ error messages
• •cat_ category names
• •skill_ skill descriptions
• •meta_ meta warnings

Rule: Never mix Chinese and English in the same string. Use two locale keys instead.

Adding New Strings

1. •Add the same key to both locale files:
   • •cmd/skills-x/i18n/locales/zh.yaml
   • •cmd/skills-x/i18n/locales/en.yaml
2. •Use i18n.T / i18n.Tf in Go code.
3. •Rebuild (make build) to embed the updated YAML.
4. •Test:
   • •SKILLS_LANG=zh ./bin/skills-x list
   • •SKILLS_LANG=en ./bin/skills-x list

New Skill Description

Add a skill_<skill-name> key to both locale files. The list view reads descriptions from i18n, not from the skill file.

Example

# locales/en.yaml
init_success: "Installed: %s"

# locales/zh.yaml
init_success: "安装成功: %s"

fmt.Println(i18n.Tf("init_success", skillName))

Quick Reference

Common Mistakes

• •Only adding a key in one locale file
• •Hardcoding mixed-language strings
• •Forgetting to rebuild after YAML changes
• •Formatting with fmt.Sprintf before calling i18n.Tf