# Adding a New Language
This guide explains how to add support for a new UI language in NotebookLM MCP.
## Overview
NotebookLM MCP uses an i18n (internationalization) system to support multiple UI languages. The system works by:
1. Detecting UI elements based on localized text selectors
2. Allowing users to switch between supported languages
3. Building bilingual/multilingual selectors for elements that might appear in different languages
## Current Supported Languages
| Language | Code | File |
| -------- | ---- | ------------------ |
| French | `fr` | `src/i18n/fr.json` |
| English | `en` | `src/i18n/en.json` |
## Adding a New Language
### Step 1: Create the Locale File
Create a new JSON file in `src/i18n/` with the language code (e.g., `de.json` for German):
```bash
cp src/i18n/en.json src/i18n/de.json
```
### Step 2: Translate All Strings
Edit the new file and translate all strings. The structure must match exactly:
```json
{
"locale": "de",
"name": "Deutsch",
"description": "German UI selectors for NotebookLM",
"tabs": {
"sources": "Quellen",
"discussion": "Diskussion",
"studio": "Studio"
},
"buttons": {
"addSource": "Quelle hinzufügen",
"addNote": "Notiz hinzufügen"
// ... all other buttons
}
// ... translate all sections
}
```
**Important sections to translate:**
- `tabs` - Main navigation tabs
- `buttons` - All button labels
- `sourceTypes` - Source type menu items
- `placeholders` - Input placeholders
- `contentTypes` - Content generation types (Audio, Video, etc.)
- `contentOptions` - Video styles, presentation lengths, etc.
- `dialogs` - Dialog labels
- `actions` - Action menu items
- `status` - Status messages
- `errors` - Error messages
### Step 3: Update the Type Definition
Edit `src/i18n/index.ts` to add the new locale to the supported types:
```typescript
// Line ~106
export type SupportedLocale = 'fr' | 'en' | 'de'; // Add new code
// Line ~203-205
export function getSupportedLocales(): SupportedLocale[] {
return ['fr', 'en', 'de']; // Add new code
}
```
### Step 4: Configure Build to Copy Locale Files
Ensure the build process copies JSON files to `dist/i18n/`. Check `tsconfig.json`:
```json
{
"compilerOptions": {
// ...
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```
The locale files are copied via a post-build script. Verify in `package.json`:
```json
{
"scripts": {
"build": "tsc && npm run copy-i18n",
"copy-i18n": "cp src/i18n/*.json dist/i18n/"
}
}
```
### Step 5: Test the New Language
1. **Set up a test account** with the Google Account language set to the new language
2. **Run the switch script**:
```bash
./scripts/switch-account-language.sh --account=your-account --lang=de --show
```
3. **Verify visually** that NotebookLM UI appears in the new language
4. **Run E2E tests**:
```bash
./tests/e2e/run-e2e.sh --lang=de --account=your-account
```
### Step 6: Update Documentation
1. Update `README.md` to list the new supported language
2. Update this file to include the new language in the table
3. Update `tests/e2e/config.ts` to add the new language type
## Finding NotebookLM UI Strings
To find the correct translations for NotebookLM UI elements:
1. **Set your Google Account** to the target language
2. **Open NotebookLM** in a browser
3. **Inspect elements** to find exact text strings used
4. **Take screenshots** for reference
Common places to check:
- Tab names (Sources, Chat/Discussion, Studio)
- "Add source" button and menu
- Content generation buttons in Studio
- Dialog buttons (Cancel, Confirm, etc.)
- Error messages
## Environment Variable
The UI locale is set via environment variable:
```bash
# Set locale when starting the server
NOTEBOOKLM_UI_LOCALE=de node dist/http-wrapper.js
# Or in the start command
cmd.exe /c "cd /d D:\\path\\to\\project && set NOTEBOOKLM_UI_LOCALE=de&& node dist/http-wrapper.js"
```
## Bilingual Selector System
The i18n system includes a `SelectorBuilder` class that generates selectors for all supported languages:
```typescript
import { selectors, tAll } from './i18n/index.js';
// Build a selector that matches button text in all languages
const addSourceSelectors = selectors().buttonWithText('addSource').build();
// Returns: ['button:has-text("Ajouter une source")', 'button:has-text("Add source")', ...]
// Get translated text in all languages
const texts = tAll('buttons', 'addSource');
// Returns: ['Ajouter une source', 'Add source', ...]
```
This ensures the automation works regardless of the user's NotebookLM language setting.
## Troubleshooting
### Selectors not matching
1. Check that the translated strings match **exactly** what NotebookLM displays
2. NotebookLM may use different strings in different contexts
3. Some UI elements use aria-labels instead of visible text
### Language not changing
1. The Google Account language must be changed first
2. The Chrome profile must be regenerated (delete and re-authenticate)
3. Check server logs for `🌐 Locale set to: XX`
### Build errors
1. Ensure JSON file is valid (no trailing commas, proper quotes)
2. Ensure all required keys are present
3. Run `npm run build` and check for TypeScript errors
## File Structure
```
src/i18n/
├── index.ts # i18n system code
├── fr.json # French translations
├── en.json # English translations
└── de.json # German translations (new)
scripts/
└── switch-account-language.sh # Language switching script
tests/e2e/
├── config.ts # Test configuration (includes TestLang type)
└── run-e2e.sh # Test runner with --lang option
```
