Skip to content

docs(cli): document non-interactive setup for CI#393

Closed
JoshKappler wants to merge 1 commit into
mainfrom
docs-cli-ci-path
Closed

docs(cli): document non-interactive setup for CI#393
JoshKappler wants to merge 1 commit into
mainfrom
docs-cli-ci-path

Conversation

@JoshKappler

Copy link
Copy Markdown
Contributor

This PR is two small fixes plus the working-path documentation they point to. The fixes: the step 3 code block was titled .env though the wizard writes .env.local, and step 2 presents npx gt init as the setup wizard with no note that it is interactive. Those two point at a gap. The page tells readers to run gt translate in their CI pipeline (step 4: "Run this in your CI pipeline before you build for production"), but its own setup step cannot run in CI, so the larger addition here is a Non-interactive setup for CI section that documents the headless path. gt init only prompts and has no non-interactive flag: it accepts just --src and --config, and gt configure runs the same wizard underneath. In a non-interactive shell it cannot prompt, and npx gt init < /dev/null exits 0 without creating gt.config.json or writing credentials, so a CI script that checks the exit code sees a false success.

These quickstarts were created in the #354 docs refactor merged July 16 and had not been walked end to end yet. The docs bots do mechanical sync and grammar passes (open PR #390 is a grammar-only pass on a sibling quickstart page), so first-run gaps like this survive them.

This documents the headless path that actually works, without changing the interactive flow:

  • A warning callout at step 2 that the wizard needs a terminal and can exit successfully in CI without writing anything.
  • A "Non-interactive setup for CI" section: a minimal hand-written gt.config.json ($schema, defaultLocale, locales, and a files entry so translate has something to work on, the same shape already shown in the Configuring guide), the GT_API_KEY and GT_PROJECT_ID environment variables, and npx gt translate --config gt.config.json.
  • A filename fix: step 2 says the wizard writes .env.local (correct per the CLI source), but the step 3 code block was titled .env. Both now say .env.local.
  • One line of substrate before the steps (you need a project with a package.json and Node.js) and a success line after step 2 (you should now have gt.config.json and .env.local with the two variables).

Every flag, filename, and config field was checked against the CLI source in the gt repo (packages/cli): the wizard writes .env.local (utils/credentials.ts, cli/base.ts), init and configure are prompt-only, and translate accepts -c, --config. The full run-tests gate passes locally: unsafe-html validation, link validation, and the content build.

A maintainer might say the wizard is the intended setup path. That is true for local setup, but this page already tells readers to run gt translate in CI, so it needs a CI-safe setup path to match. If keeping setup wizard-only was deliberate, I'm happy to rescope this to just the interactive-wizard callout.

A maintainer might also say CI setup belongs in the Configuring guide, not the quickstart. This page's own step 4 already sends readers to run gt translate in CI, so the working path lives next to that instruction. If you'd rather keep the quickstart lean, I'm happy to move the section to the Configuring guide and leave a callout and a link here instead.

@JoshKappler

Copy link
Copy Markdown
Contributor Author

Folding this into #391 so the quickstart fixes are one review instead of four. The commit is cherry-picked there unchanged and the write-up moved into that PR's body.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant