CLAUDE.md

1# Claude Instructions for i18n Translation Management
2 
3## Overview
4 
5This directory contains the internationalization (i18n) message files for BirdNET-Go frontend. When working with translations, please read the comprehensive documentation in `README.md` first.
6 
7## Important Instructions
8 
91. **Read the README.md file** in this directory before making any changes to translation files
102. **Follow the established structure** documented in README.md to avoid duplication
113. **Check existing keys** before creating new ones - many common UI strings already exist
124. **Use the common namespace** for reusable UI elements across components
13 
14## Quick Reference
15 
16- Documentation: `./README.md`
17- English (base): `./en.json`
18- Other languages: `./[language-code].json`
19 
20## Key Principles
21 
221. **DRY**: Don't duplicate translations - reuse from `common.*` namespace
232. **Consistency**: Follow existing naming conventions
243. **Context**: When same word has different meanings, create specific keys
254. **Parameters**: Use `{parameter}` for dynamic content
265. **Accessibility**: Include aria-label translations
27 
28## Critical Rules
29 
30### All Languages Must Be Updated
31 
32**When adding or modifying translations, ALL translation files must be updated.**
33 
34Add new keys to `en.json` first, then run `npm run i18n:sync` from the `frontend/` directory to propagate the key structure to all 15 locale files (cs, da, de, en, es, fi, fr, hu, it, lv, nl, pl, pt, sk, sv). The sync script fills missing keys with the English value as fallback; translate those fallbacks afterward.
35 
36After editing `en.json`, also run `npm run generate:i18n-types` to regenerate the committed TypeScript key types (`src/lib/i18n/types.generated.ts`) and commit the result.
37 
38The pre-commit hook runs `i18n:sync --check` (locale files in sync) and `generate:i18n-types:check` (TypeScript types in sync); both are also enforced in CI. Commits and CI fail if either is out of sync.
39 
40### Software Terminology Context
41 
42All translations must align with **software and application terminology**, not general or alternative meanings:
43 
44| Term      | Correct Context                          | Incorrect Context        |
45| --------- | ---------------------------------------- | ------------------------ |
46| Dashboard | Application dashboard (main UI overview) | Car dashboard            |
47| Settings  | Application settings/preferences         | Physical device settings |
48| Log       | Event log, logging output                | Wooden log               |
49| Stream    | Audio/video stream, data stream          | River stream             |
50| Filter    | Data filter, search filter               | Coffee filter            |
51| Cache     | Data cache, browser cache                | Hidden storage           |
52| Terminal  | Command-line terminal                    | Airport terminal         |
53| Port      | Network port                             | Harbor port              |
54 
55When translating, always consider the software context of BirdNET-Go as a bird sound identification application.
56 
57Please ensure you understand the translation structure before making modifications.
58