@drone1/alt 0.9.3 → 1.0.0

package/package.json

@@ -1,13 +1,17 @@
 {
   "type": "module",
   "name": "@drone1/alt",
-  "version": "0.9.3",
+  "version": "1.0.0",
   "description": "An AI-powered localization tool",
   "main": "src/index.mjs",
   "bin": {
     "alt": "./alt.mjs"
   },
   "scripts": {
+    "test": "ALT_TEST=1 mocha",
+    "test:targeted": "ALT_TEST=1 mocha --grep 'multiple target'",
+    "test": "ALT_TEST=1 mocha",
+    "test:coverage": "ALT_TEST=1 nyc mocha",
     "localize-display-strings": "./alt.mjs translate --reference-file localization/reference.js",
     "print-all-help": "rm -f help.txt && (./alt.mjs help && echo -e '\n---\n' && ./alt.mjs help translate && echo -e '\n---\n' && ./alt.mjs help list-models) > help.txt",
     "generate-toc": "./scripts/gh-md-toc --insert README.md && rm -f README.md.orig.* README.md.toc.* && echo '\n**README.md updated with new table of contents**'"
@@ -46,5 +50,19 @@
   },
   "engines": {
     "node": ">=14.0.0"
+  },
+  "nyc": {
+    "check-coverage": true,
+    "per-file": true,
+    "lines": 80,
+    "statements": 80,
+    "functions": 80,
+    "branches": 80
+  },
+  "devDependencies": {
+    "chai": "^5.2.0",
+    "execa": "^9.5.2",
+    "mocha": "^11.1.0",
+    "nyc": "^17.1.0"
   }
 }

package/src/commands/list-models.js

@@ -2,5 +2,6 @@ import { loadTranslationProvider } from '../lib/provider.js'
 
 export async function runListModels({ appState, options, log }) {
 	const { apiKey, api } = await loadTranslationProvider({ __dirname: appState.__dirname, providerName: options.provider, log })
+	log.I(`Available models:\n`)
 	return log.I(await api.listModels(apiKey))
 }

package/src/commands/translate.js

@@ -35,21 +35,41 @@ export async function runTranslation({ appState, options, log }) {
 		// Validate provider
 		const providerName = (options.provider ?? config.provider)?.toLowerCase()
 		if (!VALID_TRANSLATION_PROVIDERS.includes(providerName)) {
-			log.E(`Error: Unknown provider "${providerName}". Supported providers: ${VALID_TRANSLATION_PROVIDERS.join(', ')}`)
-			process.exit(2)
+			throw new Error(
+				(providerName
+					? localizeFormatted({
+						token: 'error-unknown-provider',
+						data: { providerName },
+						lang: appState.lang,
+						log
+					})
+					: localize({
+						token: 'error-no-provider-specified',
+						lang: appState.lang,
+						log
+					}))
+				+ localizeFormatted({
+					token: 'supported-providers',
+					data: { providers: VALID_TRANSLATION_PROVIDERS.join(', ') },
+					lang: appState.lang,
+					log
+				})
+			)
 		}
 
 		const referenceLanguage = options.referenceLanguage || config.referenceLanguage
 		if (!referenceLanguage || !referenceLanguage.length) {
-			log.E(`Error: No reference language specified. Use --reference-language option or add 'referenceLanguages' to your config file`)
-			process.exit(2)
+			throw new Error(
+				localize({ token: 'error-no-reference-language', lang: appState.lang, log })
+			)
 		}
 
 		// Get target languages from CLI or config
 		const targetLanguages = options.targetLanguages || config.targetLanguages
 		if (!targetLanguages || !targetLanguages.length) {
-			log.E(`Error: No target languages specified. Use --target-languages option or add 'targetLanguages' to your config file`)
-			process.exit(2)
+			throw new Error(
+				localize({ token: 'error-no-target-languages', lang: appState.lang, log })
+			)
 		}
 
 		const normalizeOutputFilenames = options.normalizeOutputFilenames || config.normalizeOutputFilenames
@@ -71,8 +91,17 @@ export async function runTranslation({ appState, options, log }) {
 		// Copy to a temp location first so we can ensure it has an .mjs extension
 		const referenceData = await loadReferenceFile({ appLang: appState.lang, options, tmpDir, log })
 		if (!referenceData) {
-			log.E(`No reference data found in variable "${options.referenceExportedVarName}" in ${options.referenceFile}`)
-			process.exit(2)
+			throw new Error(
+				localizeFormatted({
+					token: 'error-no-reference-data-in-variable',
+					data: {
+						referenceExportedVarName: options.referenceExportedVarName,
+						referenceFile: options.referenceFile
+					},
+					lang: appState.lang,
+					log
+				})
+			)
 		}
 
 		const referenceHash = calculateHash(await readFileAsText(options.referenceFile))
@@ -94,6 +123,8 @@ export async function runTranslation({ appState, options, log }) {
 		const { apiKey, api: translationProvider } = await loadTranslationProvider({ __dirname: appState.__dirname, providerName, log })
 		log.V(`translation provider "${providerName}" loaded`)
 
+		log.D(`options.lookForContextData=${options.lookForContextData}`)
+		log.D(`config.lookForContextData=${config.lookForContextData}`)
 		const addContextToTranslation = options.lookForContextData || config.lookForContextData
 
 		const workQueue = []
@@ -132,9 +163,11 @@ export async function runTranslation({ appState, options, log }) {
 			if (addContextToTranslation) {
 				keysToProcess = keysToProcess
 					.filter(key => !isContextKey({
+						appLang: appState.lang,
 						key,
 						contextPrefix,
-						contextSuffix
+						contextSuffix,
+						log
 					}))
 			}
 

package/src/lib/config.js

@@ -16,7 +16,7 @@ export async function loadConfig({ configFile, refFileDir, log }) {
 	return await readJsonFile(configFilePath) || {
 		provider: null,
 		targetLanguages: [],
-		lookForContextData: true,
+		lookForContextData: false,
 		contextPrefix: '',
 		contextSuffix: '',
 		referenceLanguage: null,

package/src/lib/context-keys.js

@@ -1,10 +1,19 @@
-export function isContextKey({ key, contextPrefix, contextSuffix }) {
+import { localizeFormatted } from '../localizer/localize.js'
+
+export function isContextKey({ appLang, key, contextPrefix, contextSuffix, log }) {
 	if (contextPrefix?.length) return key.startsWith(contextPrefix)
 	if (contextSuffix?.length) return key.endsWith(contextSuffix)
-	throw new Error(`Either the context prefix or context suffix must be defined`)
+	log.D(`contextPrefix=${contextPrefix}`)
+	log.D(`contextSuffix=${contextSuffix}`)
+	throw new Error(
+		localizeFormatted({
+			token: 'error-context-prefix-and-suffix-not-defined',
+			lang: appLang,
+			log
+		})
+	)
 }
 
 export function formatContextKeyFromKey({ key, prefix, suffix }) {
 	return `${prefix}${key}${suffix}`
 }
-

package/src/lib/io.js

@@ -7,6 +7,7 @@ import { ensureExtension, normalizeKey } from './utils.js'
 import { assertIsObj, assertValidPath } from './assert.js'
 import { pathToFileURL } from 'url'
 import { CWD } from './consts.js'
+import { localizeFormatted } from '../localizer/localize.js'
 
 export async function mkTmpDir() {
 	return await fsp.mkdtemp(path.join(os.tmpdir(), 'alt-'))
@@ -57,15 +58,21 @@ export function rmDir(dir, log) {
 }
 
 // This is basically so that we can dynamically import .js files by copying them to temp .mjs files, to avoid errors from node
-export async function copyFileToTempAndEnsureExtension({ filePath, tmpDir, ext }) {
+export async function copyFileToTempAndEnsureExtension({ appLang, filePath, tmpDir, ext, log }) {
 	try {
 		const fileName = ensureExtension(path.basename(filePath), ext)
 		const destPath = path.join(tmpDir, fileName)
 		await fsp.copyFile(filePath, destPath)
 		return destPath
 	} catch (error) {
-		log.E(`Error copying file to temp directory: ${error.message}`)
-		throw error
+		throw new Error(
+			localizeFormatted({
+				token: 'error-copying-file-to-temp-dir',
+				data: { error: error.message },
+				lang: appLang,
+				log
+			})
+		)
 	}
 }
 

package/src/lib/reference-loader.js

@@ -24,6 +24,7 @@ export async function loadReferenceFile({ appLang, options: { referenceFile, ref
 
 			// For .js, we need to copy to a temp location as an .mjs so we can dynamically import
 			const tmpReferencePath = await copyFileToTempAndEnsureExtension({
+				appLang,
 				filePath: referenceFile,
 				tmpDir,
 				ext: 'mjs',

package/src/main.mjs

@@ -81,7 +81,7 @@ export async function run() {
 			const command = this.name()
 			const options = this.opts()
 
-			if (options.logo) {
+			if (options.logo && process.env.ALT_TEST !== '1') {
 				await printLogo({
 					fontsSrcDir: path.resolve(__dirname, '../assets/figlet-fonts/'),
 					tagline: p.description,
@@ -111,7 +111,7 @@ export async function run() {
 				.option('-c, --config-file <path>', `Path to config file; defaults to <output dir>/${DEFAULT_CONFIG_FILENAME}`)
 				.option('-rl, --reference-language <language>', `The reference file's language; overrides any 'referenceLanguage' config setting`)
 				.option('-o, --output-dir <path>', 'Output directory for localized files')
-				.option('-l, --target-languages <list>', `Comma-separated list of language codes; overrides any 'targetLanguages' config setting`, value => languageList(value, log))
+				.option('-tl, --target-languages <list>', `Comma-separated list of language codes; overrides any 'targetLanguages' config setting`, value => languageList(value, log))
 				.option('-k, --keys <list>', 'Comma-separated list of keys to process', keyList)
 				.option('-R, --reference-exported-var-name <var name>', `For .js or .mjs reference files, this will be the exported variable, e.g. for 'export default = {...}' you'd use 'default' here, or 'data' for 'export const data = { ... }'. For .json or .jsonc reference files, this value is ignored.`, 'default')
 				.option('-m, --app-context-message <message>', `Description of your app to give context. Passed with each translation request; overrides any 'appContextMessage' config setting`)

package/test/README.md

@@ -0,0 +1,37 @@
+# ALT Testing Guide
+
+This directory contains tests for the ALT localization tool, using Mocha, Chai, and Execa.
+
+## Test Structure
+
+- `mock.test.js`: Simple tests that run without external dependencies
+- `cli-translation.test.js`: Tests for the core translation CLI functionality
+- `config.test.js`: Tests for configuration handling
+- `list-models.test.js`: Tests for the list-models command
+- `localization.test.js`: Tests for the localization system
+- `main-cli.test.js`: Tests for the main CLI interface
+- `translate-command.test.js`: Tests for the translate command
+
+## Setup
+ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY must be set in order to run some tests.
+
+## Running Tests
+
+Run all tests (requires API keys):
+```
+npm test
+```
+
+Run specific test:
+```
+npx mocha --grep "test description"
+```
+
+Run tests with coverage:
+```
+npm run test:coverage
+```
+
+## Test Data
+
+The `fixtures` directory contains test fixtures used by the tests.

package/test/common.mjs

@@ -0,0 +1,29 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { DEFAULT_CACHE_FILENAME } from '../src/lib/consts.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+export const SRC_DATA_DIR = path.join(__dirname, 'fixtures')
+
+export function cleanupCacheFile(dir) {
+	cleanupFile(path.resolve(dir, DEFAULT_CACHE_FILENAME))
+}
+
+export function ensureDir(dir) {
+	if (fs.existsSync(dir)) return
+	fs.mkdirSync(dir, { recursive: true })
+}
+
+export function cleanupFile(file) {
+	if (!fs.existsSync(file)) return
+	fs.unlinkSync(file)
+}
+
+export function cleanupDir(dir) {
+	if (!fs.existsSync(dir)) return
+	fs.rmdirSync(dir, { recursive: true })
+}
+
+

package/test/config.test.js

@@ -0,0 +1,78 @@
+import { expect } from 'chai'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { dirname } from 'path'
+import { execa } from 'execa'
+import { cleanupCacheFile, cleanupDir, cleanupFile, ensureDir, SRC_DATA_DIR } from './common.mjs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const TEST_CONFIG_DIR = path.join(__dirname, 'test-config')
+
+describe('config functionality', () => {
+  before(() => {
+    // Create test directory if it doesn't exist
+    ensureDir(TEST_CONFIG_DIR)
+  })
+
+  afterEach(() => {
+    // Clean up test config file after each test
+    const configPath = path.join(TEST_CONFIG_DIR, 'config.json')
+    cleanupFile(configPath)
+  })
+
+  after(() => {
+    cleanupDir(TEST_CONFIG_DIR)
+    cleanupCacheFile(SRC_DATA_DIR)
+  })
+
+  it('should use custom config file when specified', async function() {
+    this.timeout(5000)
+
+    // Create a custom config file
+    const configPath = path.join(TEST_CONFIG_DIR, 'config.json')
+    const configContent = {
+      provider: 'anthropic',
+      targetLanguages: [
+        'fr-FR',
+        'es-ES'
+      ],
+      lookForContextData: true,
+      contextPrefix: 'TEST_PREFIX',
+      contextSuffix: 'TEST_SUFFIX',
+      referenceLanguage: 'en',
+      normalizeOutputFilenames: true
+    }
+
+    fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2))
+
+    // Create a simple reference file for testing
+    const refPath = path.join(TEST_CONFIG_DIR, 'reference.js')
+    fs.writeFileSync(refPath, 'export default { "test-key": "This is a test" }')
+
+    try {
+      // Run the CLI with the custom config
+      const result = await execa('node', [
+        path.resolve(__dirname, '../alt.mjs'),
+        'translate',
+        '-r',
+        refPath,
+        '--config-file',
+        configPath,
+        '--debug'
+      ])
+
+      // Command should succeed
+      expect(result.exitCode).to.equal(0)
+
+      // Output should include info from our config
+      expect(result.stdout).to.include('anthropic')
+      expect(result.stdout).to.include('fr-FR')
+      expect(result.stdout).to.include('es-ES')
+    } finally {
+      // Clean up reference file
+      cleanupFile(refPath)
+    }
+  })
+})

package/test/fixtures/reference.js

@@ -0,0 +1,5 @@
+export default {
+	'msg-test': `Nothing to do`,
+	'error-finished': `Finished with %%errorsEncountered%% error%%s%%`,
+  '_context:msg-finished': `This is a message displayed at the end of the app run`
+}

package/test/fixtures/reference.json

@@ -0,0 +1,5 @@
+{
+	"msg-test": "Nothing to do",
+	"error-finished": "Finished with %%errorsEncountered%% error%%s%%",
+  "_context:msg-finished": "This is a message displayed at the end of the app run"
+}

package/test/fixtures/reference.jsonc

@@ -0,0 +1,8 @@
+{
+  // Some great stuff here
+	"msg-test": "Nothing to do",
+	"error-finished": "Finished with %%errorsEncountered%% error%%s%%",
+
+  // Context keys
+  "_context:msg-finished": "This is a message displayed at the end of the app run"
+}

package/test/list-models.test.js

@@ -0,0 +1,27 @@
+import { execa } from 'execa'
+import { expect } from 'chai'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { dirname } from 'path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+describe('list-models command', () => {
+  it('should display models from a specific provider when specified', async () => {
+    // Run with specific provider (using anthropic as example)
+    const result = await execa('node', [
+      path.resolve(__dirname, '../alt.mjs'),
+      'list-models',
+      '-p',
+      'anthropic'
+    ])
+
+    // Check the command executed successfully
+    expect(result.exitCode).to.equal(0)
+
+    // Output should include provider-specific information
+    expect(result.stdout).to.include('Available models')
+  })
+})

package/test/localization.test.js

@@ -0,0 +1,124 @@
+import { expect } from 'chai'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { dirname } from 'path'
+import { isBcp47LanguageTagValid, isDefaultLanguage, initLocalizer } from '../src/localizer/localize.js'
+import { LANGTAG_DEFAULT } from '../src/lib/consts.js'
+import { ensureDir, cleanupDir } from './common.mjs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const TEST_LOCALIZATION_DIR = path.join(__dirname, 'test-localization')
+
+describe('localization functionality', () => {
+  before(() => {
+    // Create test directory if it doesn't exist
+    ensureDir(TEST_LOCALIZATION_DIR)
+
+    // Create a simple English localization file
+    const enContent = {
+      "test_key": "This is a test",
+      "hello_world": "Hello, World!",
+      "formatted_string": "Hello, %%name%%!"
+    }
+    fs.writeFileSync(path.join(TEST_LOCALIZATION_DIR, 'en.json'), JSON.stringify(enContent, null, 2))
+
+    // Create a simple French localization file
+    const frContent = {
+      "test_key": "C'est un test",
+      "hello_world": "Bonjour, Monde!",
+      "formatted_string": "Bonjour, %%name%%!"
+    }
+    fs.writeFileSync(path.join(TEST_LOCALIZATION_DIR, 'fr-FR.json'), JSON.stringify(frContent, null, 2))
+  })
+
+  after(() => {
+    cleanupDir(TEST_LOCALIZATION_DIR)
+  })
+
+  describe('isBcp47LanguageTagValid', () => {
+    it('should validate valid BCP47 language tags', () => {
+      expect(isBcp47LanguageTagValid('en')).to.be.an('object')
+      expect(isBcp47LanguageTagValid('fr-FR')).to.be.an('object')
+      expect(isBcp47LanguageTagValid('de-DE')).to.be.an('object')
+      expect(isBcp47LanguageTagValid('zh-Hans')).to.be.an('object')
+    })
+
+    it('should reject invalid BCP47 language tags', () => {
+      expect(isBcp47LanguageTagValid('not-a-language')).to.be.undefined
+      expect(isBcp47LanguageTagValid('xx-XX')).to.be.undefined
+      expect(isBcp47LanguageTagValid('')).to.be.undefined
+    })
+  })
+
+  describe('isDefaultLanguage', () => {
+    it('should identify the default language', () => {
+      expect(isDefaultLanguage(LANGTAG_DEFAULT)).to.be.true
+    })
+
+    it('should reject non-default languages', () => {
+      expect(isDefaultLanguage('fr-FR')).to.be.false
+      expect(isDefaultLanguage('es-ES')).to.be.false
+    })
+  })
+
+  describe('initLocalizer', () => {
+    it('should initialize with the default language', async () => {
+      const mockLog = {
+        D: () => {},
+        W: () => {},
+        E: () => {},
+        I: () => {},
+        V: () => {}
+      }
+
+      const lang = await initLocalizer({
+        defaultAppLanguage: 'en',
+        appLanguage: null,
+        srcDir: TEST_LOCALIZATION_DIR,
+        log: mockLog
+      })
+
+      expect(lang).to.equal('en')
+    })
+
+    it('should initialize with a specified language', async () => {
+      const mockLog = {
+        D: () => {},
+        W: () => {},
+        E: () => {},
+        I: () => {},
+        V: () => {}
+      }
+
+      const lang = await initLocalizer({
+        defaultAppLanguage: 'en',
+        appLanguage: 'fr-FR',
+        srcDir: TEST_LOCALIZATION_DIR,
+        log: mockLog
+      })
+
+      expect(lang).to.equal('fr-FR')
+    })
+
+    it('should fall back to default language when invalid language specified', async () => {
+      const mockLog = {
+        D: () => {},
+        W: () => {},
+        E: () => {},
+        I: () => {},
+        V: () => {}
+      }
+
+      const lang = await initLocalizer({
+        defaultAppLanguage: 'en',
+        appLanguage: 'invalid-language',
+        srcDir: TEST_LOCALIZATION_DIR,
+        log: mockLog
+      })
+
+      expect(lang).to.equal('en')
+    })
+  })
+})

package/test/main-cli.test.js

@@ -0,0 +1,79 @@
+import { execa } from 'execa'
+import { expect } from 'chai'
+import { fileURLToPath } from 'url'
+import { dirname } from 'path'
+import { cleanupCacheFile, SRC_DATA_DIR } from './common.mjs'
+import path from 'path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+describe('main CLI functionality', () => {
+  after(() => cleanupCacheFile(SRC_DATA_DIR))
+
+  it('should display help information', async () => {
+    // Run the help command
+    const result = await execa('node', [
+      path.resolve(__dirname, '../alt.mjs'),
+      '--help'
+    ])
+
+    // Check the command executed successfully
+    expect(result.exitCode).to.equal(0)
+
+    // Output should contain expected help information
+    expect(result.stdout).to.include('Usage:')
+    expect(result.stdout).to.include('Options:')
+    expect(result.stdout).to.include('Commands:')
+    expect(result.stdout).to.include('Environment variables:')
+  })
+
+  it('should display version information', async () => {
+    // Run the version command
+    const result = await execa('node', [
+      path.resolve(__dirname, '../alt.mjs'),
+      '--version'
+    ])
+
+    // Check the command executed successfully
+    expect(result.exitCode).to.equal(0)
+
+    // Output should contain version number
+    expect(result.stdout).to.match(/\d+\.\d+\.\d+/)
+  })
+
+  it('should display command-specific help', async () => {
+    // Run the help command for translate
+    const result = await execa('node', [
+      path.resolve(__dirname, '../alt.mjs'),
+      'help',
+      'translate'
+    ])
+
+    // Check the command executed successfully
+    expect(result.exitCode).to.equal(0)
+
+    // Output should contain expected help information for translate command
+    expect(result.stdout).to.include('Usage: alt translate')
+    expect(result.stdout).to.include('-r, --reference-file')
+    expect(result.stdout).to.include('-tl, --target-languages')
+  })
+
+  it('should return error for missing required options', async () => {
+    try {
+      // Run translate command without required options
+      await execa('node', [
+        path.resolve(__dirname, '../alt.mjs'),
+        'translate'
+      ])
+      // Should not reach here as the command should fail
+      expect.fail('Command should have failed with missing required options')
+    } catch (error) {
+      // Check that the command failed
+      expect(error.exitCode).to.not.equal(0)
+
+      // Error should mention missing required option
+      expect(error.stderr).to.include('required option')
+    }
+  })
+})

package/test/mocha.setup.js

@@ -0,0 +1,10 @@
+// Mocha setup file
+// This file sets up the environment for testing
+
+// Set timeout for all tests to 10 seconds by default
+export const mochaHooks = {
+  beforeAll() {
+    // Default timeout for tests (can be overridden in individual tests)
+    this.timeout(10000);
+  }
+};