docs

Environment variables

Build and CI

VariableExampleRequiredSafe to expose?PurposeFailure behavior
LINGUANA_PROJECT_TOKENlna_...Remote build workNoManifest and paid-work authorizationUpload/translation returns authorization failure
LINGUANA_API_URLhttps://api.example.comRemote compiler and SSRServer configuration onlyAPI origin for builds and server catalog readsRegistration or catalog load fails
LINGUANA_UPLOADtrueNoBuild config, not secretEnables manifest uploadfalse keeps extraction local
LINGUANA_TRANSLATEfalseNoBuild config, not secretCLI templates translate development builds unless this is falsefalse uploads without translating
LINGUANA_MAX_CHARGE_MICROS1000000NoBuild config, not secretPer-build translation ceiling in USD micros for CLI templatesDefaults to 1000000 ($1.00)
GIT_COMMIT_SHAGit revisionNoYesRecords source revision in the manifestManifest omits source revision
LINGUANA_PROJECT_IDProject IDCLI templatesYesProject for template builds; checked by linguana doctorConnected templates refuse to build when it is missing or differs from VITE_LINGUANA_PROJECT_ID
LINGUANA_ENVIRONMENTdevelopmentCLI templatesYesBuild environment for template buildsConnected templates refuse to build when it differs from VITE_LINGUANA_ENVIRONMENT

Browser runtime

VariableExampleRequiredSafe to expose?Purpose
VITE_LINGUANA_API_URLhttps://api.example.comRemote browser catalogsYesBrowser-reachable catalog API
VITE_LINGUANA_PUBLISHABLE_KEYpk_...Remote browser catalogsYesRead-only catalog authorization
VITE_LINGUANA_PROJECT_IDProject IDCLI templatesYesProject the browser runtime reads
VITE_LINGUANA_ENVIRONMENTdevelopmentCLI templatesYesEnvironment the browser runtime reads

Only intentionally public values should use the VITE_ prefix. Never create VITE_LINGUANA_PROJECT_TOKEN.

Written by the CLI

linguana link and linguana env pull write these values into .env.local, or .env.<environment>.local for other environments. Private and public pairs always match.

Build/server variableBrowser variableValue written
LINGUANA_PROJECT_IDVITE_LINGUANA_PROJECT_IDLinked project ID
LINGUANA_ENVIRONMENTVITE_LINGUANA_ENVIRONMENTSelected environment
LINGUANA_API_URLVITE_LINGUANA_API_URLAPI origin
LINGUANA_PROJECT_TOKENVITE_LINGUANA_PUBLISHABLE_KEYBuild token / public catalog-read key
LINGUANA_UPLOAD—true
LINGUANA_TRANSLATE—true for development, otherwise false
LINGUANA_MAX_CHARGE_MICROS—1000000

See Connect an existing app.

CLI

These variables configure the linguana command itself. They never belong in app environment files.

VariableExampleRequiredSafe to expose?Purpose
LINGUANA_AUTH_TOKENAccount sessionNoNoSupplies a CLI account session for controlled automation instead of the saved login. Project build tokens are rejected
LINGUANA_CONFIG_DIR/tmp/linguana-cliNoYesDirectory for saved CLI account sessions

See Sign in from the terminal.

Next.js

@linguanahq/next does not read environment variables by itself. Read them in next.config.ts and pass them to withLinguana. The Next.js guide uses these names:

VariablePassed toSafe to expose?Purpose
LINGUANA_PROJECT_IDprojectIdYesProject identity
LINGUANA_ENVIRONMENTenvironmentYesBuild and catalog environment
LINGUANA_API_URLapiUrl, runtime.catalogEndpointYesAPI origin for upload and catalogs
LINGUANA_PROJECT_TOKENtokenNoBuild-only upload credential
LINGUANA_UPLOADuploadBuild config, not secretEnables manifest upload during next build
LINGUANA_PUBLISHABLE_KEYruntime.publishableKeyYesCatalog-read key, shipped in public runtime configuration

No NEXT_PUBLIC_ prefix is needed: withLinguana reads values when Next.js loads its configuration and exposes only the runtime options. Never pass the project token through runtime or a NEXT_PUBLIC_ variable.

Translation provider

VariableExampleRequiredSafe to expose?Purpose
OPENROUTER_API_KEYProvider secretOpenRouter modeNoPaid translation provider authorization
OPENROUTER_MODELqwen/qwen3.8-flashProvider-dependentServer config onlySelects the provider model
TRANSLATION_PROVIDERopenrouterServer translationServer config onlySelects deterministic or live provider adapter

Documentation deployment

VariableExampleRequiredSafe to expose?Purpose
DOCS_BASE_URLhttps://docs.example.comHosted metadataYesCanonical docs and llms.txt origin
DOCS_PORT3004Deployment-dependentYesDocs service port
VITE_DOCS_URLhttps://docs.example.comLanding integrationYesBrowser-visible docs destination

Server and browser origins

The verified example uses LINGUANA_API_URL on the server and VITE_LINGUANA_API_URL in the browser because container networking and public browser origins may differ. Both must resolve the same API and project catalog scope.

See also

Tokens and environments · CI/CD · CLI command reference

Did this page get you to a working result?

On this page

No Headings