@drone1/alt 0.7.2 → 0.8.0

package/README.md

@@ -13,15 +13,46 @@
 ![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<!--ts-->
+* [AI Localization Tool](#ai-localization-tool)
+   * [Features](#features)
+   * [Installation](#installation)
+   * [Setup](#setup)
+      * [Create a reference file](#create-a-reference-file)
+      * [Running](#running)
+      * [Output](#output)
+   * [Config file](#config-file)
+   * [Adding context](#adding-context)
+      * [Application-level context](#application-level-context)
+      * [String-specific context](#string-specific-context)
+   * [Display language](#display-language)
+   * [Usage](#usage)
+   * [Examples](#examples)
+      * [Example I](#example-i)
+      * [Example II](#example-ii)
+      * [Example III](#example-iii)
+      * [Example: ALT's localized display strings](#example-alts-localized-display-strings)
+   * [Formatting](#formatting)
+   * [Translation rules](#translation-rules)
+   * [Additional notes](#additional-notes)
+      * [Delayed vs. realtime writes](#delayed-vs-realtime-writes)
+      * [CI](#ci)
+   * [PR](#pr)
+
+<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
+<!-- Added by: jonl, at: Wed Apr 16 11:56:33 AM CEST 2025 -->
+
+<!--te-->
+
 # AI Localization Tool
-Translates all source strings in a reference (`.js`,`.mjs`,`.json`,`.jsonc`) file to all target languages using AI.
+Translates all source strings in a reference (`js`,`mjs`,`json`,`jsonc`) file to all target languages using AI.
 
 ## Features
 * Loads source/reference key/value pairs from a file 
 * Localizes using AI as needed, writing to a .json file per language
 * App-level context can be specified [`appContextMessage`]
 * Additional context can be specified per string [`--contextPrefix`, `--contextSuffix`]
-* Supports multiple AI providers: Claude, OpenAI [`--provider`]
+* Supports Claude, Gemini, OpenAI [`--provider`]
 * User-modifications to output files are safe and will not be overwritten
 * Languages are specified using BCP47 tags
 
@@ -30,7 +61,10 @@ Translates all source strings in a reference (`.js`,`.mjs`,`.json`,`.jsonc`) fil
 npm install -g @drone1/alt
 ```
 ## Setup
-Create a reference file for your reference data. For example, ``reference.js``:
+### Create a reference file
+This will house your source strings via key/value pairs in your preferred language.
+
+Here's an example ``reference.js``:
 ```javascript
 export default {
 	'error-msg': `Sorry, we don't know how to do anything`,
@@ -38,22 +72,27 @@ export default {
 	'_context:success-msg': `This text is for a button when a user completes a task`
 }
 ```
-Use whatever filename you prefer, but currently a .js extension is required.
-You can specify an exported variable instead of using `default`. See `--referenceVarName`.
+Use whatever filename you prefer. `js`,`mjs`,`json`,`jsonc` extensions are supported.
 
-2. Running
+For `.js` and `.mjs` files, you can specify the name of an exported variable instead of using `default`, via `--referenceVarName`.
+
+### Running
 ```bash
 ANTHROPIC_API_KEY=<secret>
-alt translate --reference-file ./reference.js --reference-language en --target-languages aa,bo,es-MX,hi,zh-SG --provider anthropic
-```
-or
-```bash
-OPENAI_API_KEY=<secret>
-alt translate --reference-file ./reference.js --reference-language en --target-languages aa,bo,es-MX,hi,zh-SG --provider openai
+alt translate --reference-file ./reference.js --reference-language en --target-languages aa,bo,es-MX,hi,zh-Hans --provider anthropic
 ```
-These commands would iterate across all key/value pairs in the variable exported from `./reference.js` and if needed, translate.
+This command would iterate across all key/value pairs defined in `./reference.js` and translate if needed.
+
+Here are all supported providers and their required environment variable
+
+| `-p`, `--provider` | <span style="font-weight: normal;">environment variable</span> |
+|-------------------|----------------------------------------------------------------|
+| anthropic         | ANTHROPIC_API_KEY                                              |
+| google            | GOOGLE_API_KEY                                                 |
+| openai            | OPENAI_API_KEY                                                 |
 
-The examples above would write `aa.json`, `bo.json`, etc., to the current working directory.
+### Output
+The example above would write `aa.json`, `bo.json`, etc., to the current working directory.
 
 Sample output:
 ```json
@@ -65,10 +104,6 @@ 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`
 
-## Display language
-ALT CLI itself has been localized so you can use it many languages. For non-English languages, you can set the display language with the `ALT_LANGUAGE` environment variable. Please feel free to submit 
-an issue if you do not see your preferred language.
-
 ## 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 
 `--config-file`. 
@@ -79,7 +114,7 @@ config:
 {
 	"appContextMessage": "This is a description of my app",
 	"referenceLanguage": "ar",
-	"provider": "anthropic",
+	"provider": "google",
 	"lookForContextData": true,
 	"contextPrefix": "_context:",
 	"contextSuffix": "",
@@ -91,6 +126,40 @@ config:
 
 Any of the above settings can be specified using command-line arguments (`--app-context-message`, `--reference-language`, `--provider`, `--target-languages`). Command-line arguments take precedence.
 
+## Adding context
+Sometimes a string isn't enough to give context to the AI, and as a result, it may give an undesirable translation. ALT allows you to specify additional context for this reason.
+### Application-level context
+A global, application description can be specified `--app-context-message` (or `appContextMessage` in a [config](#config)).
+For example, your config may include something like:
+```json
+	"appContextMessage": "Voided is a MMORPG game based on outer space."
+```
+### String-specific context
+Context can be added for any reference key/value pairs by passing `--look-for-context-data` (or setting `lookForContextData: true` in a [config](#config)).
+
+For example, given the following reference key/value pair:
+
+```json
+	"editor-add-component": '+ Star',
+```
+This may not translate as desired, so ALT allows you to specify additional context in the form of another key/value pair. For example:
+```json
+	"_context:editor-add-component": "This is text for a button the galaxy UI, where a user can create a star"
+```
+`_context:` can be whatever you prefer here. It's specified via `--context-prefix`, or `contextPrefix` in a [config](#config).
+
+A suffix can be specified instead of (or in conjunction with) a prefix, with `--context-suffix`, or `contextSuffix` in a [config](#config). Example:
+```json
+	"editor-add-component[context]": "This is text for a button the graph editor"
+```
+In this case, `[context]` would be specified by passing `--context-suffix '[context]'` or setting `"contextSuffix": "[context]"` in a [config](#config).
+
+Further examples can be found [here](#examples).
+
+## Display language
+ALT CLI itself has been localized so you can use it many languages. You can optionally set the display language with the `ALT_LANGUAGE` environment variable. Please feel free to submit
+an issue if you do not see your preferred language.
+
 ## Usage
 ```
 Usage: alt [options] [command]
@@ -112,6 +181,7 @@ Environment variables:
   ALT_LANGUAGE                          POSIX locale used for display
 
 ---
+
 Usage: alt translate [options]
 
 Options:
@@ -141,6 +211,7 @@ Options:
   -h, --help                                    display help for command
 
 ---
+
 Usage: alt list-models [options]
 
 Options:
@@ -213,11 +284,14 @@ Internally, there is currently nothing in the prompt about this. I've tested wit
 
 Please submit an issue if it causes you any trouble.
 
-## Rules
-Translation will occur for a given target language & key if any of the following are true:
-* The reference value was modified and translation has not yet occurred for the given language/key
-* If a context value for the given target language/key is found and has been modified.
-* The `--force` flag is used
+## 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:
+* The output file does not exist
+* The output file is missing the reference key
+* The reference value was modified
+* A context value for the given target language/key is found and has been modified.
+* `-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
 later, you can just delete that key/value pair from the given file.
@@ -234,5 +308,5 @@ If you prefer to write updates to disk in real-time (anytime any output data cha
 ### CI
 You may want to use `--tty` for more useful output.
 
-## Issues
+## PR
 Feel free to fix existing issues and submit a PR, or submit a new issue.

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@drone1/alt",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "An AI-powered localization tool",
   "main": "src/index.mjs",
   "bin": {
@@ -9,7 +9,8 @@
   },
   "scripts": {
     "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"
+    "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**'"
   },
   "repository": {
     "type": "git",

package/scripts/gh-md-toc

@@ -0,0 +1,421 @@
+#!/usr/bin/env bash
+
+#
+# Steps:
+#
+#  1. Download corresponding html file for some README.md:
+#       curl -s $1
+#
+#  2. Discard rows where no substring 'user-content-' (github's markup):
+#       awk '/user-content-/ { ...
+#
+#  3.1 Get last number in each row like ' ... </span></a>sitemap.js</h1'.
+#      It's a level of the current header:
+#       substr($0, length($0), 1)
+#
+#  3.2 Get level from 3.1 and insert corresponding number of spaces before '*':
+#       sprintf("%*s", (level-1)*'"$nb_spaces"', "")
+#
+#  4. Find head's text and insert it inside "* [ ... ]":
+#       substr($0, match($0, /a>.*<\/h/)+2, RLENGTH-5)
+#
+#  5. Find anchor and insert it inside "(...)":
+#       substr($0, match($0, "href=\"[^\"]+?\" ")+6, RLENGTH-8)
+#
+
+gh_toc_version="0.10.0"
+
+gh_user_agent="gh-md-toc v$gh_toc_version"
+
+#
+# Download rendered into html README.md by its url.
+#
+#
+gh_toc_load() {
+    local gh_url=$1
+
+    if type curl &>/dev/null; then
+        curl --user-agent "$gh_user_agent" -s "$gh_url"
+    elif type wget &>/dev/null; then
+        wget --user-agent="$gh_user_agent" -qO- "$gh_url"
+    else
+        echo "Please, install 'curl' or 'wget' and try again."
+        exit 1
+    fi
+}
+
+#
+# Converts local md file into html by GitHub
+#
+# -> curl -X POST --data '{"text": "Hello world github/linguist#1 **cool**, and #1!"}' https://api.github.com/markdown
+# <p>Hello world github/linguist#1 <strong>cool</strong>, and #1!</p>'"
+gh_toc_md2html() {
+    local gh_file_md=$1
+    local skip_header=$2
+
+    URL=https://api.github.com/markdown/raw
+
+    if [ -n "$GH_TOC_TOKEN" ]; then
+        TOKEN=$GH_TOC_TOKEN
+    else
+        TOKEN_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/token.txt"
+        if [ -f "$TOKEN_FILE" ]; then
+            TOKEN="$(cat "$TOKEN_FILE")"
+        fi
+    fi
+    if [ -n "${TOKEN}" ]; then
+        AUTHORIZATION="Authorization: token ${TOKEN}"
+    fi
+
+    local gh_tmp_file_md=$gh_file_md
+    if [ "$skip_header" = "yes" ]; then
+        if grep -Fxq "<!--te-->" "$gh_src"; then
+          # cut everything before the toc
+          gh_tmp_file_md=$gh_file_md~~
+          sed '1,/<!--te-->/d' "$gh_file_md" > "$gh_tmp_file_md"
+        fi
+    fi
+
+    # echo $URL 1>&2
+    OUTPUT=$(curl -s \
+        --user-agent "$gh_user_agent" \
+        --data-binary @"$gh_tmp_file_md" \
+        -H "Content-Type:text/plain" \
+        -H "$AUTHORIZATION" \
+        "$URL")
+
+    rm -f "${gh_file_md}~~"
+
+    if [ "$?" != "0" ]; then
+        echo "XXNetworkErrorXX"
+    fi
+    if [ "$(echo "${OUTPUT}" | awk '/API rate limit exceeded/')" != "" ]; then
+        echo "XXRateLimitXX"
+    else
+        echo "${OUTPUT}"
+    fi
+}
+
+
+#
+# Is passed string url
+#
+gh_is_url() {
+    case $1 in
+        https* | http*)
+            echo "yes";;
+        *)
+            echo "no";;
+    esac
+}
+
+#
+# TOC generator
+#
+gh_toc(){
+    local gh_src=$1
+    local gh_src_copy=$1
+    local gh_ttl_docs=$2
+    local need_replace=$3
+    local no_backup=$4
+    local no_footer=$5
+    local indent=$6
+    local skip_header=$7
+
+    if [ "$gh_src" = "" ]; then
+        echo "Please, enter URL or local path for a README.md"
+        exit 1
+    fi
+
+
+    # Show "TOC" string only if working with one document
+    if [ "$gh_ttl_docs" = "1" ]; then
+
+        echo "Table of Contents"
+        echo "================="
+        echo ""
+        gh_src_copy=""
+
+    fi
+
+    if [ "$(gh_is_url "$gh_src")" == "yes" ]; then
+        gh_toc_load "$gh_src" | gh_toc_grab "$gh_src_copy" "$indent"
+        if [ "${PIPESTATUS[0]}" != "0" ]; then
+            echo "Could not load remote document."
+            echo "Please check your url or network connectivity"
+            exit 1
+        fi
+        if [ "$need_replace" = "yes" ]; then
+            echo
+            echo "!! '$gh_src' is not a local file"
+            echo "!! Can't insert the TOC into it."
+            echo
+        fi
+    else
+        local rawhtml
+        rawhtml=$(gh_toc_md2html "$gh_src" "$skip_header")
+        if [ "$rawhtml" == "XXNetworkErrorXX" ]; then
+             echo "Parsing local markdown file requires access to github API"
+             echo "Please make sure curl is installed and check your network connectivity"
+             exit 1
+        fi
+        if [ "$rawhtml" == "XXRateLimitXX" ]; then
+             echo "Parsing local markdown file requires access to github API"
+             echo "Error: You exceeded the hourly limit. See: https://developer.github.com/v3/#rate-limiting"
+             TOKEN_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/token.txt"
+             echo "or place GitHub auth token here: ${TOKEN_FILE}"
+             exit 1
+        fi
+        local toc
+        toc=`echo "$rawhtml" | gh_toc_grab "$gh_src_copy" "$indent"`
+        echo "$toc"
+        if [ "$need_replace" = "yes" ]; then
+            if grep -Fxq "<!--ts-->" "$gh_src" && grep -Fxq "<!--te-->" "$gh_src"; then
+                echo "Found markers"
+            else
+                echo "You don't have <!--ts--> or <!--te--> in your file...exiting"
+                exit 1
+            fi
+            local ts="<\!--ts-->"
+            local te="<\!--te-->"
+            local dt
+            dt=$(date +'%F_%H%M%S')
+            local ext=".orig.${dt}"
+            local toc_path="${gh_src}.toc.${dt}"
+            local toc_createdby="<!-- Created by https://github.com/ekalinin/github-markdown-toc -->"
+            local toc_footer
+            toc_footer="<!-- Added by: `whoami`, at: `date` -->"
+            # http://fahdshariff.blogspot.ru/2012/12/sed-mutli-line-replacement-between-two.html
+            # clear old TOC
+            sed -i"${ext}" "/${ts}/,/${te}/{//!d;}" "$gh_src"
+            # create toc file
+            echo "${toc}" > "${toc_path}"
+            if [ "${no_footer}" != "yes" ]; then
+                echo -e "\n${toc_createdby}\n${toc_footer}\n" >> "$toc_path"
+            fi
+
+            # insert toc file
+            if ! sed --version > /dev/null 2>&1; then
+                sed -i "" "/${ts}/r ${toc_path}" "$gh_src"
+            else
+                sed -i "/${ts}/r ${toc_path}" "$gh_src"
+            fi
+            echo
+            if [ "${no_backup}" = "yes" ]; then
+                rm "$toc_path" "$gh_src$ext"
+            fi
+            echo "!! TOC was added into: '$gh_src'"
+            if [ -z "${no_backup}" ]; then
+                echo "!! Origin version of the file: '${gh_src}${ext}'"
+                echo "!! TOC added into a separate file: '${toc_path}'"
+        fi
+            echo
+        fi
+    fi
+}
+
+#
+# Grabber of the TOC from rendered html
+#
+# $1 - a source url of document.
+#      It's need if TOC is generated for multiple documents.
+# $2 - number of spaces used to indent.
+#
+gh_toc_grab() {
+
+    href_regex="/href=\"[^\"]+?\"/"
+    common_awk_script='
+                     modified_href = ""
+                     split(href, chars, "")
+                     for (i=1;i <= length(href); i++) {
+                         c = chars[i]
+                         res = ""
+                         if (c == "+") {
+                             res = " "
+                         } else {
+                             if (c == "%") {
+                                 res = "\\x"
+                             } else {
+                                 res = c ""
+                             }
+                         }
+                         modified_href = modified_href res
+                    }
+                    print sprintf("%*s", (level-1)*'"$2"', "") "* [" text "](" gh_url  modified_href ")"
+                    '
+    if [ "`uname -s`" == "OS/390" ]; then
+        grepcmd="pcregrep -o"
+        echoargs=""
+        awkscript='{
+                     level = substr($0, 3, 1)
+                     text = substr($0, match($0, /<\/span><\/a>[^<]*<\/h/)+11, RLENGTH-14)
+                     href = substr($0, match($0, '$href_regex')+6, RLENGTH-7)
+                     '"$common_awk_script"'
+                }'
+    else
+        grepcmd="grep -Eo"
+        echoargs="-e"
+        awkscript='{
+                     level = substr($0, 3, 1)
+                     text = substr($0, match($0, /">.*<\/h/)+2, RLENGTH-5)
+                     href = substr($0, match($0, '$href_regex')+6, RLENGTH-7)
+                     '"$common_awk_script"'
+                }'
+    fi
+
+    # if closed <h[1-6]> is on the new line, then move it on the prev line
+    # for example:
+    #   was: The command <code>foo1</code>
+    #        </h1>
+    #   became: The command <code>foo1</code></h1>
+    sed -e ':a' -e 'N' -e '$!ba' -e 's/\n<\/h/<\/h/g' |
+
+    # Sometimes a line can start with <span>. Fix that.
+    sed -e ':a' -e 'N' -e '$!ba' -e 's/\n<span/<span/g' |
+
+    # find strings that corresponds to template
+    $grepcmd '<h.*class="heading-element".*</a' |
+
+    # remove code tags
+    sed 's/<code>//g' | sed 's/<\/code>//g' |
+
+    # remove g-emoji
+    sed 's/<g-emoji[^>]*[^<]*<\/g-emoji> //g' |
+
+    # now all rows are like:
+    #   <h1 class="heading-element">title</h1><a href="..."><span>..</span></a>
+    # format result line
+    #   * $0 - whole string
+    #   * last element of each row: "</hN" where N in (1,2,3,...)
+    echo $echoargs "$(awk -v "gh_url=$1" "$awkscript")"
+}
+
+        # perl -lpE 's/(\[[^\]]*\]\()(.*?)(\))/my ($pre, $in, $post)=($1, $2, $3) ; $in =~ s{\+}{ }g; $in =~ s{%}{\\x}g; $pre.$in.$post/ems')"
+
+#
+# Returns filename only from full path or url
+#
+gh_toc_get_filename() {
+    echo "${1##*/}"
+}
+
+show_version() {
+    echo "$gh_toc_version"
+    echo
+    echo "os:     `uname -s`"
+    echo "arch:   `uname -m`"
+    echo "kernel: `uname -r`"
+    echo "shell:  `$SHELL --version`"
+    echo
+    for tool in curl wget grep awk sed; do
+        printf "%-5s: " $tool
+        if type $tool &>/dev/null; then
+            $tool --version | head -n 1
+        else
+            echo "not installed"
+        fi
+    done
+}
+
+show_help() {
+    local app_name
+    app_name=$(basename "$0")
+    echo "GitHub TOC generator ($app_name): $gh_toc_version"
+    echo ""
+    echo "Usage:"
+    echo "  $app_name [options] src [src]   Create TOC for a README file (url or local path)"
+    echo "  $app_name -                     Create TOC for markdown from STDIN"
+    echo "  $app_name --help                Show help"
+    echo "  $app_name --version             Show version"
+    echo ""
+    echo "Options:"
+    echo "  --indent <NUM>      Set indent size. Default: 3."
+    echo "  --insert            Insert new TOC into original file. For local files only. Default: false."
+    echo "                      See https://github.com/ekalinin/github-markdown-toc/issues/41 for details."
+    echo "  --no-backup         Remove backup file. Set --insert as well. Default: false."
+    echo "  --hide-footer       Do not write date & author of the last TOC update. Set --insert as well. Default: false."
+    echo "  --skip-header       Hide entry of the topmost headlines. Default: false."
+    echo "                      See https://github.com/ekalinin/github-markdown-toc/issues/125 for details."
+    echo ""
+}
+
+#
+# Options handlers
+#
+gh_toc_app() {
+    local need_replace="no"
+    local indent=3
+
+    if [ "$1" = '--help' ] || [ $# -eq 0 ] ; then
+        show_help
+        return
+    fi
+
+    if [ "$1" = '--version' ]; then
+        show_version
+        return
+    fi
+
+    if [ "$1" = '--indent' ]; then
+        indent="$2"
+        shift 2
+    fi
+
+    if [ "$1" = "-" ]; then
+        if [ -z "$TMPDIR" ]; then
+            TMPDIR="/tmp"
+        elif [ -n "$TMPDIR" ] && [ ! -d "$TMPDIR" ]; then
+            mkdir -p "$TMPDIR"
+        fi
+        local gh_tmp_md
+        if [ "`uname -s`" == "OS/390" ]; then
+            local timestamp
+            timestamp=$(date +%m%d%Y%H%M%S)
+            gh_tmp_md="$TMPDIR/tmp.$timestamp"
+        else
+            gh_tmp_md=$(mktemp "$TMPDIR/tmp.XXXXXX")
+        fi
+        while read -r input; do
+            echo "$input" >> "$gh_tmp_md"
+        done
+        gh_toc_md2html "$gh_tmp_md" | gh_toc_grab "" "$indent"
+        return
+    fi
+
+    if [ "$1" = '--insert' ]; then
+        need_replace="yes"
+        shift
+    fi
+
+    if [ "$1" = '--no-backup' ]; then
+        need_replace="yes"
+        no_backup="yes"
+        shift
+    fi
+
+    if [ "$1" = '--hide-footer' ]; then
+        need_replace="yes"
+        no_footer="yes"
+        shift
+    fi
+
+    if [ "$1" = '--skip-header' ]; then
+        skip_header="yes"
+        shift
+    fi
+
+
+    for md in "$@"
+    do
+        echo ""
+        gh_toc "$md" "$#" "$need_replace" "$no_backup" "$no_footer" "$indent" "$skip_header"
+    done
+
+    echo ""
+    echo "<!-- Created by https://github.com/ekalinin/github-markdown-toc -->"
+}
+
+#
+# Entry point
+#
+gh_toc_app "$@"

package/src/commands/translate.js

@@ -33,7 +33,7 @@ export async function runTranslation({ appState, options, log }) {
 		})
 
 		// Validate provider
-		const providerName = options.provider ?? config.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)
@@ -305,7 +305,7 @@ export async function runTranslation({ appState, options, log }) {
 				}
 			], {
 				concurrent: false, // Process languages one by one
-				...(options.tty ? { renderer: 'simple' } : {}),
+				...((options.tty || options.trace || options.debug || options.verbose) ? { renderer: 'simple' } : {}),
 				rendererOptions: { collapse: false, clearOutput: false },
 				registerSignalListeners: true,
 				collapseSubtasks: false
@@ -395,7 +395,7 @@ export async function processTranslationTask({ appState, taskInfo, listrTask, op
 			log.V(`Keeping existing translation and hash for ${targetLang}/${key}...`)
 
 			// Allow the user to directly edit/tweak output key values
-			listrTask.output = localizeFormatted({ token: 'msg-no-updated-needed-for-key', data: { key }, lang: appState.lang, log })
+			listrTask.output = localizeFormatted({ token: 'msg-no-update-needed-for-key', data: { key }, lang: appState.lang, log })
 		}
 	}
 
@@ -580,7 +580,7 @@ async function translateTextViaProvider({
 		}
 
 		if (!errorHandled) {
-			log.W(`${providerName} API failed. Error:`, error?.message ?? error)
+			log.W(`${providerName} API failed.`, error?.message ?? error)
 		}
 	}
 }

package/src/lib/consts.js

@@ -6,12 +6,14 @@ export const LANGTAG_DEFAULT = LANGTAG_ENGLISH
 
 export const VALID_TRANSLATION_PROVIDERS = [
 	'anthropic',
+	'google',
 	'openai'
 ]
 
 export const ENV_VARS = [
 	{ name: 'ANTHROPIC_API_KEY', description: 'Your Anthropic API key' },
 	{ name: 'OPENAI_API_KEY', description: 'Your OpenAI API key' },
+	{ name: 'GOOGLE_API_KEY', description: 'Your Google Gemini API key' },
 	{ name: 'ALT_LANGUAGE', description: 'POSIX locale used for display' }
 ]
 
@@ -30,6 +32,7 @@ export const SUPPORTED_REFERENCE_FILE_EXTENSIONS = [
 
 export const DEFAULT_LLM_MODELS = {
 	anthropic: 'claude-3-7-sonnet-20250219',
+	google: 'gemini-2.0-flash',
 	openai: 'gpt-4-turbo'
 }
 

package/src/main.mjs

@@ -125,9 +125,9 @@ export async function run() {
 				.option('-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`)
 				.option('-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`)
 				.option('-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`, false)
-				.option('-v, --verbose', `Enables verbose spew`, false)
-				.option('-d, --debug', `Enables debug spew`, false)
-				.option('-t, --trace', `Enables trace spew`, false)
+				.option('-v, --verbose', `Enables verbose spew; forces --tty mode`, false)
+				.option('-d, --debug', `Enables debug spew; forces --tty mode`, false)
+				.option('-t, --trace', `Enables trace spew; forces --tty mode`, false)
 				.option('--dev', `Enable dev mode, which prints stack traces with errors`, false)
 				.hook('preAction', cmd => {
 					const opts = cmd.opts()

package/src/providers/google.mjs

@@ -0,0 +1,80 @@
+export function name() {
+	return 'Google'
+}
+
+export async function listModels(apiKey) {
+	let allModels = []
+	let pageToken = null
+	let hasMore = true
+
+	while (hasMore) {
+		const url = new URL('https://generativelanguage.googleapis.com/v1/models')
+
+		// Add API key as query parameter
+		url.searchParams.append('key', apiKey)
+
+		// Add page token if we have one
+		if (pageToken) {
+			url.searchParams.append('pageToken', pageToken)
+		}
+
+		const response = await fetch(url, {
+			method: 'GET',
+			headers: {
+				'Content-Type': 'application/json'
+			}
+		})
+
+		const result = await response.json()
+
+		if (result.models && result.models.length > 0) {
+			allModels = [
+				...allModels,
+				...result.models
+			]
+
+			// Check if there's another page
+			if (result.nextPageToken) {
+				pageToken = result.nextPageToken
+			} else {
+				hasMore = false
+			}
+		} else {
+			hasMore = false
+		}
+	}
+
+	return { models: allModels }
+}
+
+export function getTranslationRequestDetails({ model, messages, apiKey, log }) {
+	return {
+		url: `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`,
+		params: {
+			contents: messages.map(m => ({
+				role: 'user',
+				parts: [ { text: m } ]
+			}))
+		},
+		config: {
+			headers: {
+				'Content-Type': 'application/json'
+			}
+		}
+	}
+}
+
+export function getResult(response, log) {
+	return response.data.candidates?.[0]?.content?.parts?.[0]?.text?.trim?.() || ''
+}
+
+function getHeader(headers, name) {
+	return headers[name] || headers.get?.(name)
+}
+
+export function getSleepInterval(headers, log) {
+	log.T(headers)
+	const retryAfter = parseInt(getHeader(headers, 'retry-after'))
+	log.D('retryAfter', retryAfter)
+	return isNaN(retryAfter) ? 0 : 1000 * retryAfter + 200
+}

package/test/reference.js

@@ -0,0 +1,28 @@
+export default {
+	'msg-nothing-to-do': `Nothing to do`,
+	'msg-finished-with-errors': `Finished with %%errorsEncountered%% error%%s%%`,
+
+	'msg-translating': 'Translating...',
+	'msg-translating-key': `Translating %%key%%`,
+	'msg-preparing-endpoint-config': `Preparing endpoint configuration...`,
+	'msg-hitting-provider-endpoint': `Hitting %%providerName%% endpoint%%attemptStr%%...`,
+
+	'msg-no-update-needed-for-key': `No update needed for %%key%%`,
+	'msg-rate-limited-sleeping': `Rate limited; sleeping for %%interval%%s...%%attemptStr%%`,
+	'msg-show-translation-result': `Translated %%key%%: "%%newValue%%"`,
+	'msg-processing-lang-and-key': `[%%progress%%%] Processing %%targetLang%% – %%key%%...`,
+
+	'msg-translation-reason-forced': `Forced update`,
+	'msg-translation-reason-outputFileDidNotExist': `Output file %%outputFile%% did not exist`,
+	'msg-translation-reason-userMissingReferenceValueHash': `No reference hash found`,
+	'msg-translation-reason-userModifiedReferenceValue': `User modified reference string`,
+	'msg-translation-reason-missingOutputKey': `No existing translation found`,
+	'msg-translation-reason-missingOutputValueHash': `No hash found in cache file`,
+
+	'error-value-not-a-string': `Value for reference key "%%key%%" was "%%type%%". Expected a string! Skipping...`,
+	'error-value-not-in-reference-data': `Key "%%key%%" did not exist in reference file`,
+	'error-translation-failed': `Translation failed for target language=%%targetLang%%; key=%%key%%; text=%%refValue%%`,
+	'error-bad-reference-file-ext': `Unsupported file type for reference file "%%ext%%"`,
+	'error-reference-var-not-found-in-data': `Couldn't find "%%referenceExportedVarName%%" in reference file "%%referenceFile%%". Did you mean one of these instead?: %%possibleKeys%%`,
+	'error-reference-file-load-failed': `Failed to load reference file "%%referenceFile%%"`
+}

package/test/reference.json

@@ -0,0 +1,28 @@
+{
+	"msg-nothing-to-do": "Nothing to do",
+	"msg-finished-with-errors": "Finished with %%errorsEncountered%% error%%s%%",
+
+	"msg-translating": "Translating...",
+	"msg-translating-key": "Translating %%key%%",
+	"msg-preparing-endpoint-config": "Preparing endpoint configuration...",
+	"msg-hitting-provider-endpoint": "Hitting %%providerName%% endpoint%%attemptStr%%...",
+
+	"msg-no-update-needed-for-key": "No update needed for %%key%%",
+	"msg-rate-limited-sleeping": "Rate limited; sleeping for %%interval%%s...%%attemptStr%%",
+	"msg-show-translation-result": "Translated %%key%%: \"%%newValue%%\"",
+	"msg-processing-lang-and-key": "[%%progress%%%] Processing %%targetLang%% – %%key%%...",
+
+	"msg-translation-reason-forced": "Forced update",
+	"msg-translation-reason-outputFileDidNotExist": "Output file %%outputFile%% did not exist",
+	"msg-translation-reason-userMissingReferenceValueHash": "No reference hash found",
+	"msg-translation-reason-userModifiedReferenceValue": "User modified reference string",
+	"msg-translation-reason-missingOutputKey": "No existing translation found",
+	"msg-translation-reason-missingOutputValueHash": "No hash found in cache file",
+
+	"error-value-not-a-string": "Value for reference key \"%%key%%\" was \"%%type%%\". Expected a string! Skipping...",
+	"error-value-not-in-reference-data": "Key \"%%key%%\" did not exist in reference file",
+	"error-translation-failed": "Translation failed for target language=%%targetLang%%; key=%%key%%; text=%%refValue%%",
+	"error-bad-reference-file-ext": "Unsupported file type for reference file \"%%ext%%\"",
+	"error-reference-var-not-found-in-data": "Couldn't find \"%%referenceExportedVarName%%\" in reference file \"%%referenceFile%%\". Did you mean one of these instead?: %%possibleKeys%%",
+	"error-reference-file-load-failed": "Failed to load reference file \"%%referenceFile%%\""
+}

package/test/reference.jsonc

@@ -0,0 +1,29 @@
+{
+	"msg-nothing-to-do": "Nothing to do",
+	"msg-finished-with-errors": "Finished with %%errorsEncountered%% error%%s%%",
+
+	"msg-translating": "Translating...",
+	"msg-translating-key": "Translating %%key%%",
+	"msg-preparing-endpoint-config": "Preparing endpoint configuration...",
+	"msg-hitting-provider-endpoint": "Hitting %%providerName%% endpoint%%attemptStr%%...",
+
+	"msg-no-update-needed-for-key": "No update needed for %%key%%",
+	"msg-rate-limited-sleeping": "Rate limited; sleeping for %%interval%%s...%%attemptStr%%",
+	"msg-show-translation-result": "Translated %%key%%: \"%%newValue%%\"",
+	"msg-processing-lang-and-key": "[%%progress%%%] Processing %%targetLang%% – %%key%%...",
+
+	"msg-translation-reason-forced": "Forced update",
+	"msg-translation-reason-outputFileDidNotExist": "Output file %%outputFile%% did not exist",
+	"msg-translation-reason-userMissingReferenceValueHash": "No reference hash found",
+	"msg-translation-reason-userModifiedReferenceValue": "User modified reference string",
+	"msg-translation-reason-missingOutputKey": "No existing translation found",
+	"msg-translation-reason-missingOutputValueHash": "No hash found in cache file",
+
+  // Errors
+	"error-value-not-a-string": "Value for reference key \"%%key%%\" was \"%%type%%\". Expected a string! Skipping...",
+	"error-value-not-in-reference-data": "Key \"%%key%%\" did not exist in reference file",
+	"error-translation-failed": "Translation failed for target language=%%targetLang%%; key=%%key%%; text=%%refValue%%",
+	"error-bad-reference-file-ext": "Unsupported file type for reference file \"%%ext%%\"",
+	"error-reference-var-not-found-in-data": "Couldn't find \"%%referenceExportedVarName%%\" in reference file \"%%referenceFile%%\". Did you mean one of these instead?: %%possibleKeys%%",
+	"error-reference-file-load-failed": "Failed to load reference file \"%%referenceFile%%\""
+}