@quaso-i18n/cli 1.0.0-rc.2 → 1.0.0-rc.2.main.g0745fee
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +77 -54
- package/package.json +1 -1
- package/quaso.mjs +1571 -136
package/README.md
CHANGED
|
@@ -1,80 +1,103 @@
|
|
|
1
1
|
# @quaso-i18n/cli
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
happened, so it works the same on a laptop, in CI and for AI agents.
|
|
3
|
+
Quaso's command-line interface (CLI) uploads i18next JSON v4 and Markdown source files, downloads translations,
|
|
4
|
+
starts translation jobs, checks progress, and imports existing translations. Commands do not
|
|
5
|
+
prompt for input. JSON output and exit codes support scripts, continuous integration (CI), and AI
|
|
6
|
+
agents.
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
## Quick start
|
|
9
|
+
|
|
10
|
+
You need a Quaso instance and an API key with the `upload` scope. Create the key while signed in as an administrator,
|
|
11
|
+
in **Account → API keys**. The CLI runs on Node 22 or later and Deno 2.9 or later. Its published
|
|
12
|
+
package contains one JavaScript file with no separate runtime dependencies.
|
|
13
|
+
|
|
14
|
+
These examples follow current `main`. For a tagged release, use the matching CLI version and its
|
|
15
|
+
documentation. Install the CLI in your game repository:
|
|
10
16
|
|
|
11
17
|
```sh
|
|
12
|
-
npm install --save-dev @quaso-i18n/cli
|
|
13
|
-
|
|
18
|
+
npm install --save-dev @quaso-i18n/cli@main
|
|
19
|
+
export QUASO_HOSTNAME=translate.yourgame.com
|
|
20
|
+
export QUASO_API_KEY='your upload API key'
|
|
21
|
+
npx quaso init --languages de,fr,pl
|
|
14
22
|
```
|
|
15
23
|
|
|
16
|
-
|
|
24
|
+
Replace the hostname and key with your values. These environment commands use a POSIX shell.
|
|
25
|
+
Check the generated `quaso.config.json` before uploading: by default it reads English source files
|
|
26
|
+
from `src/locales/en/**/*.json` and writes translations to `src/locales/{lang}/{path}`.
|
|
17
27
|
|
|
18
28
|
```sh
|
|
19
|
-
|
|
20
|
-
|
|
29
|
+
npx quaso upload --dry-run
|
|
30
|
+
npx quaso upload
|
|
31
|
+
npx quaso download
|
|
32
|
+
npx quaso status --fail-on untranslated
|
|
21
33
|
```
|
|
22
34
|
|
|
23
|
-
|
|
24
|
-
`
|
|
35
|
+
Translate on the website between upload and download. With a Gemini key configured, use
|
|
36
|
+
`npx quaso translate` to start and wait for a translation job. Upload can also start a job when
|
|
37
|
+
automatic translation is enabled; use `npx quaso upload --wait` to wait for it.
|
|
25
38
|
|
|
26
|
-
|
|
39
|
+
For Deno, replace `npx quaso` with `deno run -A npm:@quaso-i18n/cli@main`.
|
|
27
40
|
|
|
28
|
-
|
|
41
|
+
## Connecting
|
|
29
42
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
"files": [{ "source": "src/locales/en/**/*.json", "translation": "src/locales/{lang}/{path}" }],
|
|
36
|
-
"limits": [{ "file": "store.json", "key": "title", "maxLength": 30 }]
|
|
37
|
-
}
|
|
38
|
-
```
|
|
43
|
+
`QUASO_HOSTNAME` accepts a hostname, which uses HTTPS, or a full URL such as
|
|
44
|
+
`http://localhost:8000`; plain `http://` is only for `localhost`, `127.0.0.1` and `[::1]`. The API
|
|
45
|
+
key comes only from `QUASO_API_KEY`; never commit it. With a key set, the CLI only connects to
|
|
46
|
+
`QUASO_HOSTNAME` and refuses a `hostname` that only the config file names, so a cloned repository
|
|
47
|
+
can't send your key to its own server.
|
|
39
48
|
|
|
40
|
-
|
|
41
|
-
|
|
49
|
+
For an administrator's key, the `read` scope permits download and status; `upload` also permits
|
|
50
|
+
upload, import, and translation jobs. Each key follows its creator's current permissions. A
|
|
51
|
+
manager's upload key can translate assigned languages but cannot upload, import, download, or
|
|
52
|
+
read status. Deleting the creator's account disables the key. Commit the config and package lockfile so the team shares the same
|
|
53
|
+
paths and CLI version.
|
|
42
54
|
|
|
43
55
|
## Commands
|
|
44
56
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
57
|
+
Run `npx quaso <command> --help` for every option. The main commands are:
|
|
58
|
+
|
|
59
|
+
| Command | Purpose |
|
|
60
|
+
| ----------------- | ----------------------------------------------------------------------------------------- |
|
|
61
|
+
| `init` | Create a config; use `--from-crowdin` to convert a Crowdin layout. |
|
|
62
|
+
| `upload` | Send source files and report changes; preview with `--dry-run`. |
|
|
63
|
+
| `download` | Write translations; use `--at` for a published version from a past time. |
|
|
64
|
+
| `translate` | Start a translation job and wait; preview its scope with `--dry-run`. |
|
|
65
|
+
| `status` | Show progress; use `--fail-on untranslated,outdated,green` to enforce release conditions. |
|
|
66
|
+
| `import` | Read existing translations as `--as green` or `--as blue`; preview with `--dry-run`. |
|
|
67
|
+
| `version`, `help` | Print the version or command help. |
|
|
54
68
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
69
|
+
By default, download includes current accepted values, including outdated translations. Pending suggestions
|
|
70
|
+
are excluded. Missing translations use source text unless the config sets `untranslated` to
|
|
71
|
+
`omit`. Set `outdated` to `omit` to leave out older-source translations. Your app must supply
|
|
72
|
+
source-language text for omitted entries. `status --fail-on` has no condition for quality assurance (QA) errors; review those counts
|
|
73
|
+
separately.
|
|
74
|
+
|
|
75
|
+
Every command accepts `--json`, `--cwd <dir>`, `--config <path>`, `--help`, and `--version`.
|
|
76
|
+
With `--json`, the CLI writes one JSON result or handled error to stdout, with a `schemaVersion`.
|
|
77
|
+
Progress and errors go to stderr. Set `NO_COLOR` to disable terminal colors.
|
|
58
78
|
|
|
59
79
|
## Exit codes
|
|
60
80
|
|
|
61
|
-
| Code | Meaning
|
|
62
|
-
| ---- |
|
|
63
|
-
| 0 |
|
|
64
|
-
| 1 |
|
|
65
|
-
| 2 |
|
|
66
|
-
| 3 |
|
|
67
|
-
| 4 |
|
|
68
|
-
| 5 |
|
|
69
|
-
| 6 |
|
|
70
|
-
| 7 |
|
|
81
|
+
| Code | Meaning |
|
|
82
|
+
| ---- | ----------------------------------------------------------------------- |
|
|
83
|
+
| 0 | Success. |
|
|
84
|
+
| 1 | Unexpected error. |
|
|
85
|
+
| 2 | Invalid usage or config. |
|
|
86
|
+
| 3 | Authentication or permission problem. |
|
|
87
|
+
| 4 | Network or server failure; check the instance before repeating a write. |
|
|
88
|
+
| 5 | Invalid source file, such as a duplicate JSON key. |
|
|
89
|
+
| 6 | Some items were refused or failed; read the result for details. |
|
|
90
|
+
| 7 | A `status --fail-on` condition is met. |
|
|
71
91
|
|
|
72
92
|
## Safety
|
|
73
93
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
94
|
+
Download keeps files with local edits and exits with code 6; import the changes or review them
|
|
95
|
+
before using `--overwrite-local`. Keep `.quaso/` ignored by Git. `--prune` does not protect local
|
|
96
|
+
edits in files whose source is gone, so check its dry-run list before deleting them.
|
|
97
|
+
|
|
98
|
+
The CLI checks output paths before writing and refuses writes outside the project folder or over
|
|
99
|
+
source files. It does not follow HTTP redirects, start other programs, or run Git. Use previews,
|
|
100
|
+
review downloaded changes, and run your game tests before committing translations.
|
|
78
101
|
|
|
79
|
-
|
|
80
|
-
|
|
102
|
+
See the [full CLI reference](https://github.com/explodi/quaso/blob/main/docs/cli.md) for config
|
|
103
|
+
fields, command options, JSON results, retry behavior, and safety checks.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quaso-i18n/cli",
|
|
3
|
-
"version": "1.0.0-rc.2",
|
|
3
|
+
"version": "1.0.0-rc.2.main.g0745fee",
|
|
4
4
|
"description": "The command line of Quaso, localization for i18next JSON files: upload, download, status and import, from a laptop, from CI and for AI agents",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|