Skip to content

Commit 4691c9b

Browse files
lacolacolacolaco
authored
feat: add AGENTS.md and vendor-neutral agent skills (#1201)
* feat: add vendor-neutral agent skills for repository operations Add update-origin, translate-file and prh-terminology skills under .agents/skills in Agent Skills format. update-origin keeps its classification and verification scripts and per-role instruction files. * feat: add AGENTS.md with project rules for AI agents * fix: point role files to the AGENTS.md translation rules section by its heading * fix: make the role execution rule consistent for harnesses without delegation
1 parent 5978b04 commit 4691c9b

17 files changed

Lines changed: 2416 additions & 0 deletions

‎.agents/skills/prh-terminology/SKILL.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
name: prh-terminology
3+
description: "Manage the translation terminology dictionary prh.yml for consistent Angular-ja documentation. Use before adopting a translation for a new technical term, when checking existing terminology rules, and when adding, changing, or removing rules in prh.yml."
4+
---
5+
6+
# prh-terminology: Terminology dictionary management
7+
8+
Maintain the Angular-ja project's translation terminology dictionary in `prh.yml` so that Japanese technical terms stay consistent across all Angular documentation translations.
9+
10+
**Rule**: Never guess terminology. Check `prh.yml` (and apply this skill) before adopting a translation for a new technical term. Typical moments:
11+
12+
- Before any translation work: check the existing rules for the terms in the file.
13+
- For a new technical term: decide a consistent Japanese form.
14+
- For katakana standardization: verify long vowel marks and spelling.
15+
- After translating: add rules so the chosen form is enforced project-wide.
16+
17+
## prh.yml structure overview
18+
19+
The `prh.yml` file uses the prh (Proofreading Helper) format to enforce consistent terminology:
20+
21+
```yaml
22+
version: 1
23+
imports:
24+
- path: ./node_modules/prh/prh-rules/files/markdown.yml
25+
rules:
26+
- expected: 正しい表記 # Preferred term
27+
pattern: # Terms to replace
28+
- 間違った表記1
29+
- 間違った表記2
30+
options: # Optional settings
31+
wordBoundary: true # Match whole words only
32+
```
33+
34+
## Rule categories
35+
36+
### 1. 言い換え (Paraphrasing rules)
37+
38+
Standardizes Japanese technical expressions.
39+
40+
- "依存性の注入" (preferred) vs "依存関係の注入" (to replace)
41+
- "変更検知" (preferred) vs "変更検出" (to replace)
42+
43+
### 2. カタカナ語 (Katakana rules)
44+
45+
Enforces consistent katakana spelling and English preservation.
46+
47+
- **Long vowel consistency**: "サーバー" not "サーバ"
48+
- **English preservation**: "Promise" not "プロミス"
49+
- **Regex patterns**: `/pattern(?!suffix)/` to match specific cases
50+
51+
## How to add or modify rules
52+
53+
### Simple paraphrasing rule
54+
55+
```yaml
56+
- expected: 推奨される表記
57+
pattern:
58+
- 置き換える表記1
59+
- 置き換える表記2
60+
```
61+
62+
### Katakana consistency rule
63+
64+
```yaml
65+
- expected: サーバー
66+
pattern: /サーバ(?!ー)/ # Matches "サーバ" not followed by "ー"
67+
```
68+
69+
### English preservation rule
70+
71+
```yaml
72+
- expected: Promise
73+
pattern: プロミス
74+
```
75+
76+
### Complex regex rule
77+
78+
```yaml
79+
- expected: ため
80+
pattern: /(行|作)?為(?!替)/
81+
regexpMustEmpty: $1 # Captured group must be empty
82+
```
83+
84+
### Word boundary rule
85+
86+
```yaml
87+
- expected: Service Worker
88+
pattern:
89+
- サービスワーカー
90+
options:
91+
wordBoundary: true # Match whole words only
92+
```
93+
94+
## Management procedures
95+
96+
### Add a new rule
97+
98+
1. **Identify category**: paraphrasing or katakana.
99+
2. **Determine the preferred form**: based on project standards.
100+
3. **List incorrect forms**: common variations to replace.
101+
4. **Add appropriate options**: `wordBoundary`, regex patterns.
102+
103+
### Modify an existing rule
104+
105+
1. **Locate the existing rule**: search by expected term.
106+
2. **Update patterns**: add or remove incorrect forms.
107+
3. **Adjust options**: modify regex or boundary settings.
108+
4. **Test impact**: consider existing translations.
109+
110+
### Remove a rule
111+
112+
1. **Verify necessity**: confirm the rule is no longer needed.
113+
2. **Check dependencies**: ensure no conflicts with existing translations.
114+
3. **Document the reason**: give a clear justification for the removal.
115+
116+
## Angular-specific terminology guidelines
117+
118+
### Technical terms (keep in English)
119+
120+
- Component, Directive, Service, Pipe
121+
- Promise, Observable, Signal
122+
- Router, Guard, Resolver
123+
124+
### Japanese translations (standardize)
125+
126+
- "依存性の注入" for Dependency Injection
127+
- "変更検知" for Change Detection
128+
- "遅延読み込み" for Lazy Loading
129+
130+
### Katakana consistency
131+
132+
- Long vowel marks: アプリケーション, サーバー, ユーザー
133+
- Short forms: ブラウザ (not ブラウザー)
134+
135+
## Validation process
136+
137+
After modifying `prh.yml`:
138+
139+
1. **Test with prh**: verify the syntax is valid.
140+
2. **Run textlint** (`pnpm lint`): check integration with linting.
141+
3. **Test on sample files**: verify the rules work correctly.
142+
4. **Document changes**: update the rule rationale.
143+
144+
## Best practices
145+
146+
1. **Consistency first**: align with existing project terminology.
147+
2. **Community input**: consider Angular-ja community preferences.
148+
3. **Technical accuracy**: maintain precision in technical terms.
149+
4. **Readability**: balance consistency with natural Japanese.
150+
5. **Incremental changes**: add rules gradually to avoid disruption.
151+
152+
Always test rule changes against existing translations to ensure they improve consistency without introducing errors.

‎.agents/skills/translate-file/SKILL.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
name: translate-file
3+
description: "Translate English Angular documentation file to Japanese following strict project standards. Use when translating new .en.md/.en.ts/.en.json files into Japanese with line-count preservation, anchor IDs, and terminology consistency."
4+
---
5+
6+
Translate the file the user specifies (a path under `adev-ja/`) from English to Japanese following the angular-ja project's strict translation standards.
7+
8+
You are an expert Japanese technical translator specializing in Angular documentation translation. Follow the same approach as the project's AI translation tool with two-stage processing: translation → proofreading.
9+
10+
## Critical Translation Rules
11+
12+
**NEVER wrap the entire text in code blocks.** Always maintain original formatting.
13+
14+
**Structural Requirements:**
15+
- **Maintain EXACT line count** - input and output must have identical number of lines
16+
- **Preserve markdown structure absolutely** - never change heading levels, list markers, or indentation
17+
- **Keep empty lines as empty lines** - preserve all whitespace and spacing
18+
- **Maintain list hierarchy and markers** (*, -, +, 1., etc.)
19+
- **Preserve code blocks unchanged** - never translate content inside code blocks
20+
- **Keep URLs, filenames, and identifiers untranslated**
21+
- **Preserve HTML tags and special symbols exactly**
22+
23+
**AI Translation tool**
24+
- For Markdown files, use the translator tool: `tools/translator`.
25+
26+
**Heading ID Rules:**
27+
- For headings **below h1 level** (`<h2>` and lower), add anchor IDs based on original English heading
28+
- Convert original heading to lowercase and remove all symbols except hyphens
29+
- Format: `## Japanese Translation {#original-heading-lowercase}`
30+
- Examples:
31+
- `## How to use Angular` → `## Angularの使い方 {#how-to-use-angular}`
32+
- `### `foo.bar`` → `### `foo.bar` {#foobar}` (remove all non-hyphen symbols)
33+
- **h1 level headings get NO anchor IDs**
34+
35+
**Special Content Rules:**
36+
- **Never change special prefixes**: NOTE/TIP/HELPFUL/IMPORTANT/QUESTION/TLDR/CRITICAL remain in English
37+
- Correct: `NOTE: これは重要な情報です。`
38+
- Incorrect: `注: これは重要な情報です。`
39+
- **No spaces around English words**: `Angularの使い方` not `Angular の使い方`
40+
- **Preserve all Angular terminology**: component, directive, service, pipe, etc.
41+
42+
**Quality Standards:**
43+
- Follow textlint rules for Japanese technical writing
44+
- Use appropriate katakana for foreign terms per Ministry of Education guidelines
45+
- Maintain consistency with existing project translations
46+
- Ensure all cross-references and internal links remain functional
47+
48+
**CRITICAL: Use the `prh-terminology` skill for Terminology**
49+
- **BEFORE translating**: Follow the `prh-terminology` skill to check existing terminology rules in `prh.yml`
50+
- **When encountering new terms**: Follow the same skill for a consistent translation approach
51+
- **For uncertain katakana**: Check long vowel marks and standardization with the same skill
52+
- **After translation**: Add new terminology rules per the same skill if needed
53+
- The skill ensures all translations follow the project's terminology dictionary
54+
55+
**File Management Rules:**
56+
- **Original content preservation**: Translated Japanese file has ALWAYS corresponding `<name>.en.<ext>` file to preserve original content snapshot
57+
- **Structure matching**: Translated file MUST have the same line count and document structure to the original file
58+
- **Diff compatibility**: This enables easy comparison and tracking of changes between versions
59+
60+
**Processing Approach:**
61+
1. **Block-based translation**: Process content in heading-based blocks like the AI tool
62+
2. **Two-stage validation**: Translate first, then apply textlint-based corrections
63+
3. **Preserve technical accuracy** while making content accessible to Japanese developers
64+
4. **Maintain line correspondence** for easy diff tracking between .en.md and .md files
65+
66+
Always translate only the requested content, returning the translated text without additional explanations or wrapper text.

0 commit comments

Comments
 (0)