@drone1/alt 0.9.4 → 1.0.1

package/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Run Tests
+
+on:
+  push:
+    branches: [ '**' ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Setup Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: 'lts/*'
+        cache: 'npm'
+        
+    - name: Install dependencies
+      run: npm ci
+      
+    - name: Run tests
+      run: npm run test
+      env:
+        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

package/.mocharc.cjs

@@ -0,0 +1,13 @@
+// Mocha configuration file
+module.exports = {
+  require: 'test/mocha.setup.js',
+  spec: 'test/**/*.test.js',
+  'node-option': [
+    'experimental-vm-modules',
+    'no-warnings'
+  ],
+  timeout: 10000,
+  recursive: true,
+  parallel: false,
+  color: true
+}

package/README.md

@@ -1,3 +1,4 @@
+[![Run Tests](https://github.com/drone1/alt/actions/workflows/test.yml/badge.svg)](https://github.com/drone1/alt/actions/workflows/test.yml)
 ![Claude](https://img.shields.io/badge/Anthropic-black?logo=anthropic&logoColor=white)
 ![ChatGPT](https://img.shields.io/badge/ChatGPT-74aa9c?logo=openai&logoColor=white)
 ![Gemini](https://img.shields.io/badge/Gemini-4285F4?logo=google&logoColor=white)
@@ -99,7 +100,7 @@ Sample output:
 Note that output files can be lower-cased if you pass the ``--normalize-output-filenames`` option, so `fr-FR` translations would write to `fr-fr.json`
 
 ## Config file
-[_optional_] You can create a config file. By default, `ALT` will search the output directory for `config.json`, but you can specify a path directly using 
+[_optional_] You can create a config file. By default, ALT will search the output directory for `config.json`, but you can specify a path directly using 
 `--config-file`. 
 Example 
 config:
@@ -172,6 +173,7 @@ Commands:
 Environment variables:
   ANTHROPIC_API_KEY                     Your Anthropic API key
   OPENAI_API_KEY                        Your OpenAI API key
+  GOOGLE_API_KEY                        Your Google Gemini API key
   ALT_LANGUAGE                          BCP47 language tag used for display
 
 ---
@@ -183,23 +185,23 @@ Options:
   -c, --config-file <path>                      Path to config file; defaults to <output dir>/config.json
   -rl, --reference-language <language>          The reference file's language; overrides any 'referenceLanguage' config setting
   -o, --output-dir <path>                       Output directory for localized files
-  -l, --target-languages <list>                 Comma-separated list of language codes; overrides any 'targetLanguages' config setting
+  -tl, --target-languages <list>                Comma-separated list of language codes; overrides any 'targetLanguages' config setting
   -k, --keys <list>                             Comma-separated list of keys to process
   -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: "default")
   -m, --app-context-message <message>           Description of your app to give context. Passed with each translation request; overrides any 'appContextMessage' config setting
   -f, --force                                   Force regeneration of all translations (default: false)
   -rtw, --realtime-writes                       Write updates to disk immediately, rather than on shutdown (default: false)
   -y, --tty                                     Use tty/simple renderer; useful for CI (default: false)
-  -M, --model <name>                            LLM model name to use; defaults are: for "anthropic": "claude-3-7-sonnet-20250219", for "openai": "gpt-4-turbo"; use the 'list-models' command to view all models
+  -M, --model <name>                            LLM model name to use; defaults are: for "anthropic": "claude-3-7-sonnet-20250219", for "google": "gemini-2.0-flash", for "openai": "gpt-4-turbo"; use the 'list-models' command to view all models
   -x, --max-retries <integer>                   Maximum retries on failure (default: 3)
   -n, --normalize-output-filenames              Normalizes output filenames (to all lower-case); overrides any 'normalizeOutputFilenames' in config setting (default: false)
   -N, --no-logo                                 Suppress logo printout
   -cp, --context-prefix <value>                 String to be prefixed to all keys to search for additional context, which are passed along to the AI for context
   -cs, --context-suffix <value>                 String to be suffixed to all keys to search for additional context, which are passed along to the AI for context
   -L, --look-for-context-data                   If specified, ALT will pass any context data specified in the reference file to the AI provider for translation. At least one of --contextPrefix or --contextSuffix must be specified (default: false)
-  -v, --verbose                                 Enables verbose spew (default: false)
-  -d, --debug                                   Enables debug spew (default: false)
-  -t, --trace                                   Enables trace spew (default: false)
+  -v, --verbose                                 Enables verbose spew; forces --tty mode (default: false)
+  -d, --debug                                   Enables debug spew; forces --tty mode (default: false)
+  -t, --trace                                   Enables trace spew; forces --tty mode (default: false)
   --dev                                         Enable dev mode, which prints stack traces with errors (default: false)
   -p, --provider <name>                         AI provider to use for translations (anthropic, openai); overrides any 'provider' config setting
   -h, --help                                    display help for command
@@ -212,7 +214,7 @@ Options:
   -p, --provider <name>  AI provider to use for translations (anthropic,
                          openai); overrides any 'provider' config setting
   -h, --help             display help for command
-``` 
+```
 
 ## Examples
 ### Example I
@@ -279,20 +281,27 @@ Internally, there is currently nothing in the prompt about this. I've tested wit
 Please submit an issue if it causes you any trouble.
 
 ## Translation rules
-When does ALT translate a given source string? Translation will occur for a given target language & reference key/value if any of the following are true:
+Under what conditions will ALT translate a given source string?
+
+Translation will occur for a given target language & reference key/value if any of the following are true:
+
 * The output file does not exist
+  * Example: You're translating to target language _zh-Hans_ and `zh-Hans.json` doesn't exist
 * The output file is missing the reference key
+  * Example: You're translating reference key _error-msg_ to target language _zh-Hant.jso_ and `zh-Hans.json` does not have a key/value pair for key _error-msg_
 * The reference value was modified
-* A context value for the given target language/key is found and has been modified.
+  * Example: You change the value of _some-key_ in your reference file
+* A context value for the given target language/key is found and has been modified
+  * Example: You modify the value of _context:error-msg_ in your reference file. _error-msg_ will be re-translated for all target languages.
 * `-f` or `--force` are specified
 * The cache file (`.localization.cache.json`) is not present
 
-Translation will _not_ occur if `alt` detects that the given value in the target language file has been manually modified. If you modify an output value manually and want it to be re-translated
+NOTE: Translation will _not_ occur if ALT detects that the given value in the target language file has been manually modified. If you modify an output value manually and want it to be re-translated
 later, you can just delete that key/value pair from the given file.
 
 ## Additional notes
 ### Delayed vs. realtime writes
-By default, `alt` will not write to disk until the tool is shutting down (including SIGTERM &ndash; yes, `Ctrl+C` is safe).
+By default, ALT will not write to disk until the tool is shutting down (including SIGTERM &ndash; yes, `Ctrl+C` is safe).
 
 This behavior is useful if your application is monitoring the output directory and you don't want your server 
 constantly restarting, for example.