xcstrings-cli 1.0.0

package/src/commands/_shared.ts

@@ -0,0 +1,63 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+export interface XCStrings {
+    sourceLanguage: string;
+    strings: Record<string, XCStringUnit>;
+    version?: string;
+}
+
+export interface XCStringUnit {
+    comment?: string;
+    extractionState?: 'manual' | 'migrated' | 'stale' | 'ucheck';
+    localizations?: Record<string, XCStringLocalization>;
+    shouldTranslate?: boolean;
+}
+
+export interface XCStringLocalization {
+    stringUnit: {
+        state: 'translated' | 'needs_review' | 'new';
+        value: string;
+    };
+}
+
+export async function readXCStrings(path: string): Promise<XCStrings> {
+    const content = await readFile(path, 'utf-8');
+    return JSON.parse(content) as XCStrings;
+}
+
+export async function writeXCStrings(path: string, data: XCStrings): Promise<void> {
+    const json = JSON.stringify(data, null, 2);
+    const formatted = formatXCStrings(json);
+    await writeFile(path, formatted + '\n', 'utf-8');
+}
+
+export function formatXCStrings(json: string): string {
+    let result = '';
+    let inString = false;
+    let escape = false;
+
+    for (let i = 0; i < json.length; i++) {
+        const char = json[i];
+        if (inString && char === '\\' && !escape) {
+            escape = true;
+            result += char;
+            continue;
+        }
+        if (escape) {
+            escape = false;
+            result += char;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            result += char;
+            continue;
+        }
+        if (!inString && char === ':') {
+            result += ' :';
+            continue;
+        }
+        result += char;
+    }
+    return result;
+}

package/src/commands/add.ts

@@ -0,0 +1,38 @@
+import { readXCStrings, writeXCStrings, XCStringUnit } from './_shared';
+
+export async function add(
+    path: string,
+    key: string,
+    comment: string | undefined,
+    strings: Record<string, string> | undefined,
+): Promise<void> {
+    const data = await readXCStrings(path);
+
+    if (!data.strings) {
+        data.strings = {};
+    }
+
+    const unit: XCStringUnit = {
+        ...data.strings[key],
+        extractionState: 'manual',
+    };
+
+    if (comment) {
+        unit.comment = comment;
+    }
+
+    if (strings) {
+        unit.localizations = unit.localizations || {};
+        for (const [lang, value] of Object.entries(strings)) {
+            unit.localizations[lang] = {
+                stringUnit: {
+                    state: 'translated',
+                    value: value,
+                },
+            };
+        }
+    }
+
+    data.strings[key] = unit;
+    await writeXCStrings(path, data);
+}

package/src/commands/index.ts

@@ -0,0 +1,5 @@
+export { add } from './add';
+export { remove } from './remove';
+export { init } from './init';
+export { languages } from './languages';
+export * from './_shared';

package/src/commands/init.ts

@@ -0,0 +1,159 @@
+import { writeFile, readdir } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import chalk from 'chalk';
+import { checkbox, confirm } from '@inquirer/prompts';
+
+const INIT_FILE_NAME = 'xcstrings-cli.json5';
+
+async function findXCStringsFiles(dir: string): Promise<string[]> {
+    const results: string[] = [];
+
+    async function walk(currentDir: string): Promise<void> {
+        try {
+            const entries = await readdir(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = resolve(currentDir, entry.name);
+                if (entry.isDirectory()) {
+                    // Skip node_modules, .git, etc.
+                    if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                        await walk(fullPath);
+                    }
+                } else if (entry.name.endsWith('.xcstrings')) {
+                    results.push(fullPath);
+                }
+            }
+        } catch {
+            // Ignore permission errors
+        }
+    }
+
+    await walk(dir);
+    return results;
+}
+
+async function findXcodeprojDirs(startDir: string): Promise<string[]> {
+    const results: string[] = [];
+    let currentDir = startDir;
+    try {
+        const entries = await readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.endsWith('.xcodeproj')) {
+                results.push(resolve(currentDir, entry.name));
+            }
+        }
+    } catch {
+        // Ignore permission errors
+    }
+    return results;
+}
+
+export async function init(): Promise<void> {
+    const cwd = process.cwd();
+
+    console.log();
+    console.log(chalk.bold.cyan('🚀 xcstrings-cli Configuration Setup'));
+    console.log(chalk.dim('─'.repeat(40)));
+    console.log();
+
+    console.log(chalk.yellow('🔍 Searching for .xcstrings files...'));
+    const xcstringsFiles = await findXCStringsFiles(cwd);
+
+    console.log(chalk.yellow('🔍 Searching for .xcodeproj directories...'));
+    const xcodeprojDirs = await findXcodeprojDirs(cwd);
+
+    console.log();
+
+    let selectedXCStrings: string[] = [];
+    if (xcstringsFiles.length > 0) {
+        console.log(chalk.green(`✓ Found ${xcstringsFiles.length} .xcstrings file(s)`));
+
+        const choices = xcstringsFiles.map((file) => ({
+            name: chalk.white(relative(cwd, file)) + chalk.dim(` (${file})`),
+            value: relative(cwd, file),
+            checked: true,
+        }));
+
+        selectedXCStrings = await checkbox({
+            message: chalk.bold('Select .xcstrings files to manage:'),
+            choices,
+        });
+    } else {
+        console.log(chalk.dim('  No .xcstrings files found in current directory'));
+    }
+
+    console.log();
+
+    let selectedXcodeproj: string[] = [];
+    if (xcodeprojDirs.length > 0) {
+        console.log(chalk.green(`✓ Found ${xcodeprojDirs.length} .xcodeproj director${xcodeprojDirs.length === 1 ? 'y' : 'ies'}`));
+
+        const choices = xcodeprojDirs.map((dir) => ({
+            name: chalk.white(relative(cwd, dir) || dir) + chalk.dim(` (${dir})`),
+            value: relative(cwd, dir) || dir,
+            checked: true,
+        }));
+
+        selectedXcodeproj = await checkbox({
+            message: chalk.bold('Select .xcodeproj directories for language detection:'),
+            choices,
+        });
+    } else {
+        console.log(chalk.dim('  No .xcodeproj directories found'));
+    }
+
+    console.log();
+    console.log(chalk.dim('─'.repeat(40)));
+    console.log();
+
+    console.log(chalk.bold('📋 Configuration Summary:'));
+    console.log();
+
+    console.log(chalk.cyan('  xcstringsPaths:'));
+    if (selectedXCStrings.length > 0) {
+        selectedXCStrings.forEach((p) => console.log(chalk.white(`    • ${p}`)));
+    } else {
+        console.log(chalk.dim('    (none)'));
+    }
+
+    console.log();
+    console.log(chalk.cyan('  xcodeprojPaths:'));
+    if (selectedXcodeproj.length > 0) {
+        selectedXcodeproj.forEach((p) => console.log(chalk.white(`    • ${p}`)));
+    } else {
+        console.log(chalk.dim('    (none)'));
+    }
+
+    console.log();
+
+    const shouldWrite = await confirm({
+        message: chalk.bold(`Create ${chalk.yellow(INIT_FILE_NAME)}?`),
+        default: true,
+    });
+
+    if (!shouldWrite) {
+        console.log(chalk.dim('  Configuration cancelled.'));
+        return;
+    }
+
+    const xcstringsArray = selectedXCStrings.map((p) => `        "${p}"`).join(',\n');
+    const xcodeprojArray = selectedXcodeproj.map((p) => `        "${p}"`).join(',\n');
+
+    const config = `{
+    // Array of paths to .xcstrings files to manage. Specify relative or absolute paths.
+    xcstringsPaths: [
+${xcstringsArray}
+    ],
+    // Array of paths to .xcodeproj directories. Used for discovering supported languages.
+    xcodeprojPaths: [
+${xcodeprojArray}
+    ]
+}
+`;
+
+    await writeFile(INIT_FILE_NAME, config, 'utf-8');
+
+    console.log();
+    console.log(chalk.bold.green(`✓ Created ${INIT_FILE_NAME}`));
+    console.log(chalk.dim(`   Run ${chalk.cyan('xcstrings --help')} to see available commands.`));
+    console.log();
+}

package/src/commands/languages.ts

@@ -0,0 +1,43 @@
+import { XcodeProject } from '@bacons/xcode';
+import { resolve } from 'node:path';
+import { loadConfig } from '../utils/config';
+import { readXCStrings } from './_shared';
+
+export function getLanguagesFromXcodeproj(xcodeprojPath: string): string[] {
+    const pbxprojPath = resolve(xcodeprojPath, 'project.pbxproj');
+    const project = XcodeProject.open(pbxprojPath);
+    const rootObject = project.rootObject;
+    return rootObject.props.knownRegions ?? [];
+}
+
+export async function getLanguagesFromXCStrings(xcstringsPath: string): Promise<string[]> {
+    const xcstrings = await readXCStrings(xcstringsPath);
+    const languages = new Set<string>();
+
+    for (const key of Object.keys(xcstrings.strings)) {
+        const unit = xcstrings.strings[key];
+        if (unit.localizations) {
+            for (const lang of Object.keys(unit.localizations)) {
+                languages.add(lang);
+            }
+        }
+    }
+
+    return Array.from(languages).sort();
+}
+
+export async function languages(
+    xcstringsPath: string,
+    configPath?: string
+): Promise<string[]> {
+    const config = await loadConfig(configPath);
+    if (config?.xcodeprojPaths && config.xcodeprojPaths.length > 0) {
+        const allLanguages = new Set<string>();
+        for (const xcodeprojPath of config.xcodeprojPaths) {
+            const langs = getLanguagesFromXcodeproj(xcodeprojPath);
+            langs.forEach((lang) => allLanguages.add(lang));
+        }
+        return Array.from(allLanguages).sort();
+    }
+    return await getLanguagesFromXCStrings(xcstringsPath);
+}

package/src/commands/remove.ts

@@ -0,0 +1,9 @@
+import { readXCStrings, writeXCStrings } from './_shared';
+
+export async function remove(path: string, key: string): Promise<void> {
+    const data = await readXCStrings(path);
+    if (data.strings && data.strings[key]) {
+        delete data.strings[key];
+        await writeXCStrings(path, data);
+    }
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { remove, init, languages } from './commands/index.js';
+import { resolve } from 'node:path';
+import { loadConfig } from './utils/config.js';
+import logger from './utils/logger.js';
+import { runAddCommand } from './utils/cli.js';
+import { select } from '@inquirer/prompts';
+import chalk from 'chalk';
+
+const defaultPath = resolve(process.cwd(), 'Localizable.xcstrings');
+
+yargs(hideBin(process.argv))
+    .scriptName('xcstrings')
+    .usage('$0 <cmd> [args]')
+    .option('config', {
+        type: 'string',
+        describe: 'Path to config file',
+    })
+    .option('path', {
+        type: 'string',
+        describe: 'Path to xcstrings file',
+        default: defaultPath
+    })
+    .middleware(async (argv) => {
+        if (argv.path !== defaultPath) {
+            return;
+        }
+
+        const config = await loadConfig(argv.config as string | undefined);
+
+        if (!config || !config.xcstringsPaths || config.xcstringsPaths.length === 0) {
+            return;
+        }
+
+        if (config.xcstringsPaths.length === 1) {
+            const entry = config.xcstringsPaths[0];
+            argv.path = typeof entry === 'string' ? entry : entry.path;
+        } else {
+            const choices = config.xcstringsPaths.map((entry) => {
+                if (typeof entry === 'string') {
+                    return { name: entry, value: entry };
+                } else {
+                    return { name: `${entry.alias} (${entry.path})`, value: entry.path };
+                }
+            });
+
+            const selectedPath = await select({
+                message: 'Select xcstrings file:',
+                choices: choices,
+            });
+            argv.path = selectedPath;
+        }
+    })
+    .command(
+        'add',
+        'Add a string',
+        (yargs) => yargs
+            .option('key', {
+                type: 'string',
+                describe: 'The key of the string',
+                demandOption: true,
+            })
+            .option('comment', {
+                type: 'string',
+                describe: 'The comment for the string',
+            })
+            .option('strings', {
+                type: 'string',
+                describe: 'The strings JSON'
+            }),
+        async (argv) => {
+            await runAddCommand(argv.path as string, argv.key as string, argv.comment as string | undefined, argv.strings as unknown);
+            logger.info(chalk.green(`✓ Added key "${argv.key}"`));
+        },
+    )
+    .command(
+        'remove',
+        'Remove a string',
+        (yargs) => yargs.option('key', {
+            type: 'string',
+            describe: 'The key to remove',
+            demandOption: true,
+        }),
+        async (argv) => {
+            await remove(argv.path as string, argv.key as string);
+            logger.info(chalk.green(`✓ Removed key "${argv.key}"`));
+        },
+    )
+    .command(
+        'init',
+        'Initialize configuration file',
+        (yargs) => yargs,
+        async () => {
+            await init();
+        },
+    )
+    .command(
+        'languages',
+        'List supported languages from xcodeproj or xcstrings',
+        (yargs) => yargs,
+        async (argv) => {
+            const result = await languages(argv.path as string, argv.config as string | undefined);
+            logger.info(result.join(' '));
+        },
+    )
+    .demandCommand(1, '')
+    .strictCommands()
+    .recommendCommands()
+    .showHelpOnFail(true)
+    .fail((msg, err, yargsInstance) => {
+        if (err) {
+            console.error(err);
+            throw err;
+        }
+        if (msg) {
+            console.error(chalk.red(msg));
+            console.log();
+        }
+        yargsInstance.showHelp();
+        process.exit(1);
+    })
+    .help()
+    .argv;

package/src/utils/cli.ts

@@ -0,0 +1,60 @@
+import { add } from '../commands/index.js';
+
+export async function readStdinToString(): Promise<string> {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            resolve(data);
+        });
+        if (process.stdin.readableEnded) {
+            resolve('');
+        }
+    });
+}
+
+export async function parseStringsArg(
+    stringsArg: unknown,
+    stdinReader: () => Promise<string> = readStdinToString,
+): Promise<Record<string, string> | undefined> {
+    if (stringsArg === undefined) {
+        return undefined;
+    }
+    if (stringsArg === '') {
+        const stdin = await stdinReader();
+        if (!stdin.trim()) return undefined;
+        return JSON.parse(stdin);
+    }
+    if (typeof stringsArg === 'string') {
+        return JSON.parse(stringsArg);
+    }
+    if (Array.isArray(stringsArg)) {
+        const merged: Record<string, string> = {};
+        for (const item of stringsArg) {
+            if (typeof item === 'string') {
+                Object.assign(merged, JSON.parse(item));
+            }
+        }
+        return merged;
+    }
+    if (typeof stringsArg === 'boolean' && stringsArg === true) {
+        const stdin = await stdinReader();
+        if (!stdin.trim()) return undefined;
+        return JSON.parse(stdin);
+    }
+    return undefined;
+}
+
+export async function runAddCommand(
+    path: string,
+    key: string,
+    comment: string | undefined,
+    stringsArg: unknown,
+    stdinReader: () => Promise<string> = readStdinToString,
+): Promise<void> {
+    const strings = await parseStringsArg(stringsArg, stdinReader);
+    await add(path, key, comment, strings);
+}

package/src/utils/config.ts

@@ -0,0 +1,32 @@
+import { cosmiconfig } from 'cosmiconfig';
+import json5 from 'json5';
+
+const moduleName = 'xcstrings-cli';
+
+const explorer = cosmiconfig(moduleName, {
+    searchPlaces: [
+        `${moduleName}.json`,
+        `${moduleName}.json5`,
+    ],
+    loaders: {
+        '.json5': async (filepath: string, content: string) => {
+            return json5.parse(content);
+        },
+    },
+    cache: false,
+});
+
+export interface Config {
+    xcstringsPaths?: (string | { alias: string; path: string })[];
+    xcodeprojPaths?: string[];
+}
+
+export async function loadConfig(explicitPath?: string): Promise<Config | null> {
+    if (explicitPath) {
+        const result = await explorer.load(explicitPath);
+        return result ? (result.config as Config) : null;
+    }
+
+    const result = await explorer.search();
+    return result ? (result.config as Config) : null;
+}

package/src/utils/logger.ts

@@ -0,0 +1,7 @@
+import pino from 'pino';
+
+const logger = pino({
+    level: process.env.LOG_LEVEL || 'info',
+});
+
+export default logger;

package/tests/cli.heredoc.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { setupTempFile, cleanupTempFiles } from './utils/testFileHelper';
+import { spawn } from 'child_process';
+
+afterEach(async () => await cleanupTempFiles());
+
+describe('cli: heredoc stdin', () => {
+    it('should accept JSON from stdin when --strings flag passed without value (heredoc)', async () => {
+        const stdin = JSON.stringify({ en: 'Hello', ja: 'こんにちは', 'zh-Hans': '你好，世界.' });
+
+        const tempFile = await setupTempFile('no-strings.xcstrings');
+
+        const node = process.execPath;
+        const cliPath = resolve(process.cwd(), 'dist', 'index.js');
+        const args = ['--enable-source-maps', cliPath, 'add', '--key', 'greeting', '--comment', 'Hello, World', '--strings', '--path', tempFile];
+
+        const child = spawn(node, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+
+        child.stdin.write(stdin);
+        child.stdin.end();
+
+        await new Promise<void>((resolvePromise, reject) => {
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (chunk) => stdout += chunk);
+            child.stderr.on('data', (chunk) => stderr += chunk);
+            child.on('exit', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`Process exited with non-zero code ${code}. Stderr: ${stderr}`));
+                } else {
+                    resolvePromise();
+                }
+            });
+        });
+
+        const content = JSON.parse(await readFile(tempFile, 'utf-8'));
+        expect(content.strings).toHaveProperty('greeting');
+        expect(content.strings.greeting.localizations.en.stringUnit.value).toBe('Hello');
+        expect(content.strings.greeting.localizations.ja.stringUnit.value).toBe('こんにちは');
+        expect(content.strings.greeting.localizations['zh-Hans'].stringUnit.value).toBe('你好，世界.');
+    });
+});

package/tests/cli.stdin.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { parseStringsArg, runAddCommand } from '../src/utils/cli';
+import { readFile } from 'node:fs/promises';
+import { setupTempFile, cleanupTempFiles } from './utils/testFileHelper';
+
+afterEach(async () => await cleanupTempFiles());
+
+describe('cli: stdin strings', () => {
+    it('parseStringsArg: should read JSON from stdin when strings option provided without value', async () => {
+        const stdin = `{
+            "en": "Hello",
+            "ja": "こんにちは",
+            "zh-Hans": "你好，世界."
+        }`;
+
+        const result = await parseStringsArg(true, async () => Promise.resolve(stdin));
+        expect(result).toBeDefined();
+        expect(result?.en).toBe('Hello');
+        expect(result?.ja).toBe('こんにちは');
+        expect(result?.['zh-Hans']).toBe('你好，世界.');
+    });
+
+    it('parseStringsArg: should read JSON from stdin when strings option provided as empty string ("")', async () => {
+        const stdin = `{"en":"Hello","ja":"こんにちは","zh-Hans":"你好，世界."}`;
+
+        const result = await parseStringsArg('', async () => Promise.resolve(stdin));
+        expect(result).toBeDefined();
+        expect(result?.en).toBe('Hello');
+        expect(result?.ja).toBe('こんにちは');
+        expect(result?.['zh-Hans']).toBe('你好，世界.');
+    });
+
+    it('add: should add strings read from stdin', async () => {
+        const stdin = `{"en":"Hello","ja":"こんにちは","zh-Hans":"你好，世界."}`;
+
+        const tempFile = await setupTempFile('no-strings.xcstrings');
+        await runAddCommand(tempFile, 'greeting', 'Hello, World', true, async () => Promise.resolve(stdin));
+
+        const content = JSON.parse(await readFile(tempFile, 'utf-8'));
+        expect(content.strings).toHaveProperty('greeting');
+        expect(content.strings.greeting.localizations.en.stringUnit.value).toBe('Hello');
+        expect(content.strings.greeting.localizations.ja.stringUnit.value).toBe('こんにちは');
+        expect(content.strings.greeting.localizations['zh-Hans'].stringUnit.value).toBe('你好，世界.');
+    });
+
+    it('parseStringsArg: should parse strings when provided as an inline JSON string', async () => {
+        const str = `{ "en": "Hello", "ja": "こんにちは" }`;
+        const result = await parseStringsArg(str, async () => Promise.resolve(''));
+        expect(result).toBeDefined();
+        expect(result?.en).toBe('Hello');
+        expect(result?.ja).toBe('こんにちは');
+    });
+
+    it('parseStringsArg: should merge arrays passed for --strings multiple times', async () => {
+        const items = ['{"en":"Hello"}', '{"ja":"こんにちは"}'];
+        const result = await parseStringsArg(items as unknown as string[], async () => Promise.resolve(''));
+        expect(result).toBeDefined();
+        expect(result?.en).toBe('Hello');
+        expect(result?.ja).toBe('こんにちは');
+    });
+});

package/tests/cli.unknown.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { resolve } from 'node:path';
+import { spawn } from 'child_process';
+
+describe('cli: unknown command', () => {
+    it('should exit non-zero and print help when unknown subcommand is passed', async () => {
+        const node = process.execPath;
+        const cliPath = resolve(process.cwd(), 'dist', 'index.js');
+        const args = ['--enable-source-maps', cliPath, 'hello'];
+
+        const child = spawn(node, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+
+        await new Promise<void>((resolvePromise) => {
+            let stderr = '';
+            child.stderr.on('data', (chunk) => stderr += chunk);
+            child.on('exit', (code) => {
+                expect(code).not.toBe(0);
+                expect(stderr).toMatch(/Unknown/i);
+                expect(stderr).toMatch(/xcstrings/);
+                resolvePromise();
+            });
+        });
+    });
+});