string-catalog-mcp 1.0.0

package/src/mcp/tools/get-catalog-statistics.ts

@@ -0,0 +1,29 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { StringCatalog } from '../../string-catalog';
+
+export function registerGetCatalogStatistics(server: McpServer) {
+    server.registerTool(
+        'get_catalog_statistics',
+        {
+            description:
+                'Get statistics about a String Catalog including total keys, supported languages, and translation coverage percentage for each language.',
+            inputSchema: {
+                filePath: z.string().describe('Absolute path to the .xcstrings file'),
+            },
+        },
+        async ({ filePath }) => {
+            const catalog = new StringCatalog(filePath);
+            const stats = catalog.getStatistics();
+
+            return {
+                content: [
+                    {
+                        type: 'text' as const,
+                        text: JSON.stringify(stats, null, 2),
+                    },
+                ],
+            };
+        }
+    );
+}

package/src/mcp/tools/get-translations-for-key.ts

@@ -0,0 +1,45 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { StringCatalog } from '../../string-catalog';
+
+export function registerGetTranslationsForKey(server: McpServer) {
+    server.registerTool(
+        'get_translations_for_key',
+        {
+            description:
+                'Get all translations for a specific key in a String Catalog. Shows the translated text in each supported language along with the translation state.',
+            inputSchema: {
+                filePath: z.string().describe('Absolute path to the .xcstrings file'),
+                key: z.string().describe('The localization key to look up'),
+            },
+        },
+        async ({ filePath, key }) => {
+            const catalog = new StringCatalog(filePath);
+            const result = catalog.getTranslationsForKey(key);
+
+            if (!result) {
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: JSON.stringify(
+                                { error: `Key "${key}" not found in catalog` },
+                                null,
+                                2
+                            ),
+                        },
+                    ],
+                };
+            }
+
+            return {
+                content: [
+                    {
+                        type: 'text' as const,
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+    );
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,16 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerListSupportedLanguages } from './list-supported-languages';
+import { registerGetTranslationsForKey } from './get-translations-for-key';
+import { registerSearchKeys } from './search-keys';
+import { registerUpdateTranslations } from './update-translations';
+import { registerGetCatalogStatistics } from './get-catalog-statistics';
+import { registerListAllKeys } from './list-all-keys';
+
+export function registerAllTools(server: McpServer) {
+    registerListSupportedLanguages(server);
+    registerGetTranslationsForKey(server);
+    registerSearchKeys(server);
+    registerUpdateTranslations(server);
+    registerGetCatalogStatistics(server);
+    registerListAllKeys(server);
+}

package/src/mcp/tools/list-all-keys.ts

@@ -0,0 +1,52 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { StringCatalog } from '../../string-catalog';
+
+export function registerListAllKeys(server: McpServer) {
+    server.registerTool(
+        'list_all_keys',
+        {
+            description:
+                'List all localization keys in a String Catalog. Returns keys sorted alphabetically.',
+            inputSchema: {
+                filePath: z.string().describe('Absolute path to the .xcstrings file'),
+                limit: z
+                    .number()
+                    .optional()
+                    .default(100)
+                    .describe('Maximum number of keys to return (default: 100)'),
+                offset: z
+                    .number()
+                    .optional()
+                    .default(0)
+                    .describe('Number of keys to skip (for pagination, default: 0)'),
+            },
+        },
+        async ({ filePath, limit: limitArg, offset: offsetArg }) => {
+            const limit = limitArg ?? 100;
+            const offset = offsetArg ?? 0;
+            const catalog = new StringCatalog(filePath);
+            const allKeys = catalog.getAllKeys();
+            const paginatedKeys = allKeys.slice(offset, offset + limit);
+
+            return {
+                content: [
+                    {
+                        type: 'text' as const,
+                        text: JSON.stringify(
+                            {
+                                keys: paginatedKeys,
+                                total: allKeys.length,
+                                offset,
+                                limit,
+                                hasMore: offset + limit < allKeys.length,
+                            },
+                            null,
+                            2
+                        ),
+                    },
+                ],
+            };
+        }
+    );
+}

package/src/mcp/tools/list-supported-languages.ts

@@ -0,0 +1,38 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { StringCatalog } from '../../string-catalog';
+
+export function registerListSupportedLanguages(server: McpServer) {
+    server.registerTool(
+        'list_supported_languages',
+        {
+            description:
+                'List all supported languages in a given Xcode String Catalog (.xcstrings) file. Returns the source language and all languages that have translations.',
+            inputSchema: {
+                filePath: z.string().describe('Absolute path to the .xcstrings file'),
+            },
+        },
+        async ({ filePath }) => {
+            const catalog = new StringCatalog(filePath);
+            const languages = catalog.getSupportedLanguages();
+            const sourceLanguage = catalog.getSourceLanguage();
+
+            return {
+                content: [
+                    {
+                        type: 'text' as const,
+                        text: JSON.stringify(
+                            {
+                                sourceLanguage,
+                                supportedLanguages: languages,
+                                count: languages.length,
+                            },
+                            null,
+                            2
+                        ),
+                    },
+                ],
+            };
+        }
+    );
+}

package/src/mcp/tools/search-keys.ts

@@ -0,0 +1,40 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { StringCatalog } from '../../string-catalog';
+
+export function registerSearchKeys(server: McpServer) {
+    server.registerTool(
+        'search_keys',
+        {
+            description:
+                'Search for localization keys containing a specific substring. Useful for finding keys when you only know part of the key name.',
+            inputSchema: {
+                filePath: z.string().describe('Absolute path to the .xcstrings file'),
+                query: z
+                    .string()
+                    .describe('Substring to search for in key names (case-insensitive)'),
+            },
+        },
+        async ({ filePath, query }) => {
+            const catalog = new StringCatalog(filePath);
+            const keys = catalog.searchKeys(query);
+
+            return {
+                content: [
+                    {
+                        type: 'text' as const,
+                        text: JSON.stringify(
+                            {
+                                query,
+                                matchingKeys: keys,
+                                count: keys.length,
+                            },
+                            null,
+                            2
+                        ),
+                    },
+                ],
+            };
+        }
+    );
+}

package/src/mcp/tools/update-translations.ts

@@ -0,0 +1,89 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { StringCatalog } from '../../string-catalog';
+
+const toolDescription = `Update or add translations to a String Catalog. Accepts an array of translation entries.
+
+IMPORTANT: iOS strings support format placeholders that must be preserved in translations:
+- %@ for strings (objects)
+- %d or %lld for integers
+- %f for floating point numbers
+- %1$@, %2$@ etc. for positional arguments (order can be changed in translations)
+
+Example input:
+{
+  "data": [
+    {
+      "key": "hello_world",
+      "translations": [
+        { "language": "en", "value": "Hello World" },
+        { "language": "de", "value": "Hallo Welt" },
+        { "language": "no", "value": "Hei Verden" }
+      ],
+      "comment": "Greeting message shown on home screen"
+    },
+    {
+      "key": "items_count",
+      "translations": [
+        { "language": "en", "value": "%lld items" },
+        { "language": "de", "value": "%lld Elemente" }
+      ]
+    }
+  ]
+}`;
+
+const translationSchema = z.object({
+    language: z.string().describe('Language code (e.g., "en", "de", "no", "vi")'),
+    value: z
+        .string()
+        .describe('The translated text. Preserve any format placeholders like %@, %lld, %d'),
+    state: z
+        .enum(['new', 'translated', 'needs_review', 'stale'])
+        .optional()
+        .describe('Translation state (defaults to "translated")'),
+});
+
+const translationsSchema = z.object({
+    key: z.string().describe('The localization key'),
+    translations: z.array(translationSchema).describe('Array of language translations'),
+    comment: z.string().optional().describe('Optional comment describing the string context'),
+});
+
+const inputSchema = z.object({
+    filePath: z.string().describe('Absolute path to the .xcstrings file'),
+    data: z.array(translationsSchema).describe('Array of translation entries to add or update'),
+});
+
+export function registerUpdateTranslations(server: McpServer) {
+    server.registerTool(
+        'update_translations',
+        {
+            description: toolDescription,
+            inputSchema,
+        },
+        async ({ filePath, data }) => {
+            const catalog = new StringCatalog(filePath);
+            const result = catalog.updateTranslations(data);
+            catalog.save();
+
+            return {
+                content: [
+                    {
+                        type: 'text' as const,
+                        text: JSON.stringify(
+                            {
+                                success: true,
+                                updatedKeys: result.updated,
+                                createdKeys: result.created,
+                                totalUpdated: result.updated.length,
+                                totalCreated: result.created.length,
+                            },
+                            null,
+                            2
+                        ),
+                    },
+                ],
+            };
+        }
+    );
+}

package/src/string-catalog.ts

@@ -0,0 +1,232 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+    XCStrings,
+    StringEntry,
+    TranslationInput,
+    KeyTranslationsResult,
+    KeyTranslation,
+    LocalizationState,
+} from './types';
+
+/**
+ * StringCatalog class for reading and manipulating .xcstrings files
+ */
+export class StringCatalog {
+    private filePath: string;
+    private data: XCStrings;
+
+    constructor(filePath: string) {
+        this.filePath = path.resolve(filePath);
+        this.data = this.load();
+    }
+
+    private load(): XCStrings {
+        if (!fs.existsSync(this.filePath)) {
+            throw new Error(`String catalog file not found: ${this.filePath}`);
+        }
+
+        const content = fs.readFileSync(this.filePath, 'utf-8');
+        return JSON.parse(content) as XCStrings;
+    }
+
+    /**
+     * Get the source language of the catalog
+     */
+    getSourceLanguage(): string {
+        return this.data.sourceLanguage;
+    }
+
+    /**
+     * Get all supported languages in the catalog
+     */
+    getSupportedLanguages(): string[] {
+        const languages = new Set<string>();
+        languages.add(this.data.sourceLanguage);
+
+        for (const key in this.data.strings) {
+            const entry = this.data.strings[key];
+            if (entry.localizations) {
+                for (const lang of Object.keys(entry.localizations)) {
+                    languages.add(lang);
+                }
+            }
+        }
+
+        return Array.from(languages).sort();
+    }
+
+    /**
+     * Get all keys in the catalog
+     */
+    getAllKeys(): string[] {
+        return Object.keys(this.data.strings).sort();
+    }
+
+    /**
+     * Get translations for a specific key
+     */
+    getTranslationsForKey(key: string): KeyTranslationsResult | null {
+        const entry = this.data.strings[key];
+        if (!entry) {
+            return null;
+        }
+
+        const translations: KeyTranslation[] = [];
+
+        if (entry.localizations) {
+            for (const [language, localization] of Object.entries(entry.localizations)) {
+                if (localization.stringUnit) {
+                    translations.push({
+                        language,
+                        value: localization.stringUnit.value,
+                        state: localization.stringUnit.state,
+                    });
+                } else if (localization.variations?.plural) {
+                    // For plural strings, show the "other" form as the primary value
+                    const plural = localization.variations.plural;
+                    const primaryForm = plural.other || plural.one || plural.zero;
+                    if (primaryForm) {
+                        translations.push({
+                            language,
+                            value: `[plural] ${primaryForm.stringUnit.value}`,
+                            state: primaryForm.stringUnit.state,
+                        });
+                    }
+                }
+            }
+        }
+
+        return {
+            key,
+            sourceLanguage: this.data.sourceLanguage,
+            translations: translations.sort((a, b) => a.language.localeCompare(b.language)),
+        };
+    }
+
+    /**
+     * Search for keys containing a specific substring
+     */
+    searchKeys(query: string): string[] {
+        const lowerQuery = query.toLowerCase();
+        return this.getAllKeys().filter((key) => key.toLowerCase().includes(lowerQuery));
+    }
+
+    /**
+     * Update translations for one or more keys
+     */
+    updateTranslations(translations: TranslationInput[]): { updated: string[]; created: string[] } {
+        const updated: string[] = [];
+        const created: string[] = [];
+
+        for (const translation of translations) {
+            const { key, translations: langTranslations, comment } = translation;
+
+            const isNew = !this.data.strings[key];
+
+            if (isNew) {
+                this.data.strings[key] = {};
+                created.push(key);
+            } else {
+                updated.push(key);
+            }
+
+            const entry = this.data.strings[key];
+
+            if (comment) {
+                entry.comment = comment;
+            }
+
+            if (!entry.localizations) {
+                entry.localizations = {};
+            }
+
+            for (const langTrans of langTranslations) {
+                entry.localizations[langTrans.language] = {
+                    stringUnit: {
+                        state: langTrans.state || 'translated',
+                        value: langTrans.value,
+                    },
+                };
+            }
+        }
+
+        return { updated, created };
+    }
+
+    /**
+     * Save changes to the file
+     */
+    save(): void {
+        // Sort keys alphabetically for consistent output
+        const sortedStrings: { [key: string]: StringEntry } = {};
+        const keys = Object.keys(this.data.strings).sort();
+
+        for (const key of keys) {
+            sortedStrings[key] = this.data.strings[key];
+        }
+
+        const output: XCStrings = {
+            sourceLanguage: this.data.sourceLanguage,
+            strings: sortedStrings,
+        };
+
+        if (this.data.version) {
+            output.version = this.data.version;
+        }
+
+        // Write with 2-space indentation to match Xcode format
+        fs.writeFileSync(this.filePath, JSON.stringify(output, null, 2) + '\n', 'utf-8');
+    }
+
+    /**
+     * Get statistics about the catalog
+     */
+    getStatistics(): {
+        totalKeys: number;
+        languages: string[];
+        translationCoverage: Record<
+            string,
+            { translated: number; total: number; percentage: number }
+        >;
+    } {
+        const languages = this.getSupportedLanguages();
+        const allKeys = this.getAllKeys();
+        const totalKeys = allKeys.length;
+
+        const translationCoverage: Record<
+            string,
+            { translated: number; total: number; percentage: number }
+        > = {};
+
+        for (const lang of languages) {
+            let translated = 0;
+
+            for (const key of allKeys) {
+                const entry = this.data.strings[key];
+                const localization = entry.localizations?.[lang];
+
+                if (localization?.stringUnit?.state === 'translated') {
+                    translated++;
+                } else if (localization?.variations?.plural) {
+                    // Count plural as translated if it has an "other" form
+                    if (localization.variations.plural.other?.stringUnit?.state === 'translated') {
+                        translated++;
+                    }
+                }
+            }
+
+            translationCoverage[lang] = {
+                translated,
+                total: totalKeys,
+                percentage: totalKeys > 0 ? Math.round((translated / totalKeys) * 100) : 0,
+            };
+        }
+
+        return {
+            totalKeys,
+            languages,
+            translationCoverage,
+        };
+    }
+}

package/src/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Types for Xcode String Catalog (.xcstrings) file format
+ */
+
+/** State of a localization string */
+export type LocalizationState = 'new' | 'translated' | 'needs_review' | 'stale';
+
+/** A single string unit containing the translation value and state */
+export interface StringUnit {
+    state: LocalizationState;
+    value: string;
+}
+
+/** Localization entry for a single language */
+export interface LocalizationEntry {
+    stringUnit?: StringUnit;
+    /** For plural variations */
+    variations?: {
+        plural?: {
+            zero?: { stringUnit: StringUnit };
+            one?: { stringUnit: StringUnit };
+            two?: { stringUnit: StringUnit };
+            few?: { stringUnit: StringUnit };
+            many?: { stringUnit: StringUnit };
+            other?: { stringUnit: StringUnit };
+        };
+        device?: Record<string, { stringUnit: StringUnit }>;
+    };
+}
+
+/** All localizations for a single string key */
+export interface StringLocalizations {
+    [languageCode: string]: LocalizationEntry;
+}
+
+/** A single string entry in the catalog */
+export interface StringEntry {
+    comment?: string;
+    extractionState?: 'manual' | 'extracted_with_value' | 'stale';
+    localizations?: StringLocalizations;
+}
+
+/** Root structure of an .xcstrings file */
+export interface XCStrings {
+    sourceLanguage: string;
+    version?: string;
+    strings: {
+        [key: string]: StringEntry;
+    };
+}
+
+/**
+ * Translation input format for the update tool
+ */
+export interface TranslationInput {
+    key: string;
+    translations: {
+        language: string;
+        value: string;
+        state?: LocalizationState;
+    }[];
+    comment?: string;
+}
+
+export interface TranslationData {
+    data: TranslationInput[];
+}
+
+/**
+ * Output format for listing translations of a key
+ */
+export interface KeyTranslation {
+    language: string;
+    value: string;
+    state: LocalizationState;
+}
+
+export interface KeyTranslationsResult {
+    key: string;
+    sourceLanguage: string;
+    translations: KeyTranslation[];
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "commonjs",
+        "lib": ["ES2022"],
+        "declaration": true,
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true,
+        "noImplicitThis": true,
+        "alwaysStrict": true,
+        "noUnusedLocals": false,
+        "noUnusedParameters": false,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": false,
+        "inlineSourceMap": true,
+        "inlineSources": true,
+        "experimentalDecorators": true,
+        "strictPropertyInitialization": false,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "resolveJsonModule": true
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+}