Translations

Overview

Obsidian Chess Studio is committed to making professional chess analysis accessible to players worldwide. The application supports 17+ languages with community-contributed translations.

Supported Languages

🇺🇸 English (US)

100% - Base language

🇪🇸 Spanish

99% - Nearly complete

🇩🇪 German

77% - Partial

🇫🇷 French

77% - Partial

🇯🇵 Japanese

77% - Partial

🇷🇺 Russian

77% - Partial

🇨🇳 Chinese

77% - Partial

🇮🇹 Italian

77% - Partial

🇵🇱 Polish

77% - Partial

Additional languages: Belarusian (77%), English UK (77%), Armenian (77%), Norwegian (77%), Portuguese (77%), Ukrainian (77%), Arabic (74%), Turkish (59%)

Translation percentages are automatically calculated based on the number of translated keys compared to English (US).

Translation Structure

Translations are organized in src/locales/ with one directory per language:

src/locales/
├── en-US/               # English (US) - Base language
│   └── common.json
├── es/                  # Spanish
│   └── common.json
├── de/                  # German
│   └── common.json
├── fr/                  # French
│   └── common.json
├── ja/                  # Japanese
│   └── common.json
├── ru/                  # Russian
│   └── common.json
├── zh/                  # Chinese
│   └── common.json
└── ...

Each language has a common.json file with nested translation keys:

{
  "common": {
    "on": "ON",
    "off": "OFF",
    "name": "Name",
    "save": "Save"
  },
  "boards": {
    "newGame": "New Game",
    "analysis": "Analysis"
  },
  "settings": {
    "appearance": "Appearance",
    "language": "Language"
  }
}

Adding a New Language

Follow these steps to add a new language to Obsidian Chess Studio:

Create Language Directory

Create a new directory using the language code:

# Example for Korean
mkdir src/locales/ko

Language codes:

Use ISO 639-1 codes (e.g., ko, vi, th)
For regional variants, use language-REGION (e.g., pt-BR, en-GB)

Copy Base Translation File

Copy the English translation as a starting point:

cp src/locales/en-US/common.json src/locales/ko/common.json

Create Index File

Create src/locales/ko/index.ts:

import common from "./common.json";

export default {
  translation: common,
};

Translate Strings

Open common.json and translate all text values:

{
  "common": {
    "on": "설정",
    "off": "해제",
    "name": "이름",
    "save": "저장"
  }
}

Keep JSON keys unchanged (e.g., "on", "name")
Only translate the values
Preserve interpolation variables like {{value}}

Edit src/i18n.ts to add your language:

// Add import
import ko from "./locales/ko";

// Add to resources
const resources = {
  "en-US": en_US,
  "ko-KR": ko,  // Add this line
  // ... other languages
};

Update Missing Translations

Run the script to add any missing keys:

pnpm scripts/update-missing-translations.ts

This automatically adds missing keys with placeholder values.

Update README

Run the script to update the README:

pnpm scripts/update-readme.ts

This updates the translation progress table.

Test Your Translation

Start the dev server and test:

pnpm dev

Open the app
Go to Settings → Language
Select your language
Navigate through the app to verify translations

Updating Existing Translations

Find Your Language

Locate the language directory:

cd src/locales/es  # Example for Spanish

Edit Translations

Open common.json and update translations:

{
  "boards": {
    "newGame": "Nueva Partida",
    "analysis": "Análisis"
  }
}

Check for Missing Keys

Run the update script:

pnpm scripts/update-missing-translations.ts

This finds keys in en-US that are missing from your language.

Test Changes

pnpm dev

Verify your changes in the running application.

Translation Scripts

Update Missing Translations

pnpm scripts/update-missing-translations.ts

What it does:

Compares each language to en-US
Adds missing keys with "[MISSING]" placeholders
Preserves existing translations
Updates all language files

Example output:

Checking es/common.json...
  Added 3 missing keys
Checking de/common.json...
  Added 15 missing keys

Update README

pnpm scripts/update-readme.ts

What it does:

Calculates translation percentage for each language
Updates the translation table in README.md
Sorts languages by completion percentage

Translation Guidelines

General Rules

Preserve Formatting

Keep special syntax unchanged:

{
  "moveCount": "Move {{number}}",
  "playerRating": "Rating: {{rating}}"
}

Translate to:

{
  "moveCount": "Jugada {{number}}",
  "playerRating": "Calificación: {{rating}}"
}

Don’t remove {{variables}}!

Chess Terminology

Use standard chess terms in your language:English → Spanish:

“Checkmate” → “Jaque mate”
“Stalemate” → “Ahogado”
“Castle” → “Enroque”
“Pawn” → “Peón”
“Knight” → “Caballo”

English → German:

“Checkmate” → “Schachmatt”
“Castle” → “Rochade”
“Knight” → “Springer”

Refer to chess.com or Lichess in your language for standard terms.

Context Matters

Some words have different meanings based on context:

{
  "common.close": "Close",        // Close a window
  "boards.close": "Close Board"   // Close a chess board
}

Check where the key is used before translating.

Keep Similar Length

Try to keep translations roughly the same length as English to avoid UI overflow:

Short: Button labels, menu items
Can be longer: Descriptions, help text

Test in the app to ensure text fits in UI components.

Special Cases

Pluralization
Date/Time Formats
Chess Notation
Keyboard Shortcuts

i18next supports pluralization:

{
  "game": "Game",
  "game_plural": "Games"
}

For languages with complex plural rules, see i18next plurals.

Keyboard shortcuts are shown in translations:

{
  "newGame": "New Game (Ctrl+N)"
}

Keep the shortcut in parentheses, but translate the action.

Testing Translations

In Development

Start Dev Server

pnpm dev

Change Language

In the app:

Go to Settings → Appearance
Select your language from the dropdown
The app reloads with your translations

Check All Screens

Navigate through:

Dashboard
Game board
Analysis panel
Settings
Dialogs and modals

Look for:

Missing translations ([MISSING] or English fallback)
UI overflow (text too long)
Grammatical errors

Automated Testing

# Run tests (includes i18n tests)
pnpm test

# Check for missing keys
pnpm scripts/update-missing-translations.ts

Submitting Translations

Create Branch

git checkout -b translation/korean

Commit Changes

git add src/locales/ko src/i18n.ts
git commit -m "feat: add Korean translation"

Run Scripts

# Update missing translations
pnpm scripts/update-missing-translations.ts

# Update README
pnpm scripts/update-readme.ts

# Commit updates
git add .
git commit -m "chore: update translation metadata"

Push and Create PR

git push origin translation/korean

Then create a pull request on GitHub with:

Title: feat: add Korean translation
Description: Translation completion percentage and any notes

Translation Progress

Check current translation status:

# View in README.md
cat README.md | grep -A 20 "TRANSLATIONS_START"

# Or run the update script to see percentages
pnpm scripts/update-readme.ts

Getting Started

Contributing

Architecture

Overview

Supported Languages

🇺🇸 English (US)

🇪🇸 Spanish

🇩🇪 German

🇫🇷 French

🇯🇵 Japanese

🇷🇺 Russian

🇨🇳 Chinese

🇮🇹 Italian

🇵🇱 Polish

Translation Structure

Adding a New Language

Updating Existing Translations

Translation Scripts

Update Missing Translations

Update README

Translation Guidelines

General Rules

Special Cases

Testing Translations

In Development

Automated Testing

Submitting Translations

Translation Progress

Getting Help

Translation Issues

Discussions

Next Steps

Contributing Guide

Development Overview

Build docs developers (and LLMs) love

Getting Started

Contributing

Architecture

​Overview

​Supported Languages

🇺🇸 English (US)

🇪🇸 Spanish

🇩🇪 German

🇫🇷 French

🇯🇵 Japanese

🇷🇺 Russian

🇨🇳 Chinese

🇮🇹 Italian

🇵🇱 Polish

​Translation Structure

​Adding a New Language

​Updating Existing Translations

​Translation Scripts

​Update Missing Translations

​Update README

​Translation Guidelines

​General Rules

​Special Cases

​Testing Translations

​In Development

​Automated Testing

​Submitting Translations

​Translation Progress

​Getting Help

Translation Issues

Discussions

​Next Steps

Contributing Guide

Development Overview

Build docs developers (and LLMs) love

Overview

Supported Languages

Translation Structure

Adding a New Language

Updating Existing Translations

Translation Scripts

Update Missing Translations

Update README

Translation Guidelines

General Rules

Special Cases

Testing Translations

In Development

Automated Testing

Submitting Translations

Translation Progress

Getting Help

Next Steps