extractTranslations
canva apps build (using @canva/cli) runs this automatically. To run it standalone, use canva-app-scripts extract-translations (using @canva/app-scripts). Call this API only for programmatic use. See Canva App Scripts for the CLI-first workflow.
Extract i18n messages from a Canva App's source files.
Loads the project's canva-app.config.{ts,…} (or the file named by
options.configFile) and applies options.overrides on top —
overrides > config file > default (the extraction options have no env
tier).
Parameters
optionsCoreCommandOptionsConfiguration overrides and config-file selection
configFilestringExplicit config file, resolved against rootDir; must exist. Unset runs
the default canva-app.config.{ts,…} discovery at the project root,
falling back to package defaults when nothing is found.
overridesCanvaAppConfigConfiguration overrides, merged over the loaded config file as the top precedence tier: overrides > env > config file > default.
Rsbuild-specific app configuration.
This is the configuration for apps using Rsbuild as the bundler.
The bundler property is optional since Rsbuild is the default.
entrystringEntry point for the app (default: 'src/index.tsx')
rootDirstringRoot directory of the project (default: process.cwd())
outputDirstringBuild output directory, relative to rootDir. build writes artefacts
here. Bundler-tier output concerns (filename, chunking) are reachable
through the bundler escape hatch, not this field.
Default
"dist"
devServerDevServerOptionsOptional dev-server options (frontend port, HTTPS, public tunnel). CLI flags and env vars override these at run time.
portnumberFrontend dev-server port. Overridden by --override-frontend-port and the
CANVA_FRONTEND_PORT env var.
Default
8080
httpsbooleanServe the frontend over HTTPS using locally-managed certificates.
Overridden by --use-https.
Default
false
backendobjectOptional backend run alongside the dev server.
When enabled, dev spawns the backend entry under nodemon with
TypeScript support, passes SSL certificate paths through to its
environment, and ties its lifecycle to the dev server — a backend crash
tears the whole process down. Apps without a backend simply omit this field.
Use true (or any backend config, even {}) to run the backend at the
default location backend/server.ts; set entry to point elsewhere.
Examples
export default defineConfig({entry: "./src/index.tsx",backend: true, // runs backend/server.ts});
export default defineConfig({entry: "./src/index.tsx",backend: { entry: "./api/main.ts", port: 3100 },});
Backend options for the dev server.
In canva-app.config.ts, any backend config (even an empty object) enables
the backend; omit the backend field entirely to run frontend-only. As a
command override, an object without entry only patches fields — true or
{ entry } opts into a run.
entrystringPath to the backend entry script, relative to rootDir, falls back to
the package default when unset.
Default
"backend/server.ts"
portnumberPort the backend listens on, used to build DevServer.backend.url.
Falls back to CANVA_BACKEND_PORT then the package default when unset.
Default
3001
hoststringBackend host the built app calls. Falls back to CANVA_BACKEND_HOST
when unset.
tunnelbooleanExpose the backend through a public HTTPS tunnel so third-party services
(OAuth providers, webhook callbacks) can reach it during local
development. Overridden by --tunnel. Requires a tunnel authtoken in env.
extractTranslationsobjectOptional configuration for extractTranslations.
outputDirstringDirectory to write extracted messages into (default: 'dist').
outputFilestringOutput filename written into outputDir (default: 'messages_en.json').
Must be a bare filename — no directory segments; use outputDir for that.
patternstringGlob for source files to scan (default: 'src/**/*.{ts,tsx}').
bundlerstringThe bundler to use for building the app. Defaults to 'rsbuild' if not specified.
The only valid value is "rsbuild".
configRsbuildConfigFnCustomize the Rsbuild configuration. Receives the base config and context, returns modified config.
Example
export default defineConfig({config: (rsbuildConfig, { mode }) => {rsbuildConfig.plugins?.push(myPlugin());return rsbuildConfig;},});
Parameters
configRsbuildConfigcontextRsbuildContextContext passed to the Rsbuild customization function.
Mirrors WebpackContext's { mode } shape for symmetry across adapters.
modestringWhether this is a development or production build.
Available values:
"production""development"
Returns
Webpack-specific app configuration.
The bundler property is required: Rsbuild is the package default, so
webpack is always an explicit opt-in.
bundlerstringThe bundler to use for building the app.
The only valid value is "webpack".
entrystringEntry point for the app (default: 'src/index.tsx')
rootDirstringRoot directory of the project (default: process.cwd())
outputDirstringBuild output directory, relative to rootDir. build writes artefacts
here. Bundler-tier output concerns (filename, chunking) are reachable
through the bundler escape hatch, not this field.
Default
"dist"
devServerDevServerOptionsOptional dev-server options (frontend port, HTTPS, public tunnel). CLI flags and env vars override these at run time.
portnumberFrontend dev-server port. Overridden by --override-frontend-port and the
CANVA_FRONTEND_PORT env var.
Default
8080
httpsbooleanServe the frontend over HTTPS using locally-managed certificates.
Overridden by --use-https.
Default
false
backendobjectOptional backend run alongside the dev server.
When enabled, dev spawns the backend entry under nodemon with
TypeScript support, passes SSL certificate paths through to its
environment, and ties its lifecycle to the dev server — a backend crash
tears the whole process down. Apps without a backend simply omit this field.
Use true (or any backend config, even {}) to run the backend at the
default location backend/server.ts; set entry to point elsewhere.
Examples
export default defineConfig({entry: "./src/index.tsx",backend: true, // runs backend/server.ts});
export default defineConfig({entry: "./src/index.tsx",backend: { entry: "./api/main.ts", port: 3100 },});
Backend options for the dev server.
In canva-app.config.ts, any backend config (even an empty object) enables
the backend; omit the backend field entirely to run frontend-only. As a
command override, an object without entry only patches fields — true or
{ entry } opts into a run.
entrystringPath to the backend entry script, relative to rootDir, falls back to
the package default when unset.
Default
"backend/server.ts"
portnumberPort the backend listens on, used to build DevServer.backend.url.
Falls back to CANVA_BACKEND_PORT then the package default when unset.
Default
3001
hoststringBackend host the built app calls. Falls back to CANVA_BACKEND_HOST
when unset.
tunnelbooleanExpose the backend through a public HTTPS tunnel so third-party services
(OAuth providers, webhook callbacks) can reach it during local
development. Overridden by --tunnel. Requires a tunnel authtoken in env.
extractTranslationsobjectOptional configuration for extractTranslations.
outputDirstringDirectory to write extracted messages into (default: 'dist').
outputFilestringOutput filename written into outputDir (default: 'messages_en.json').
Must be a bare filename — no directory segments; use outputDir for that.
patternstringGlob for source files to scan (default: 'src/**/*.{ts,tsx}').
configWebpackConfigFnCustomize the webpack configuration. Receives the base config and context, returns modified config.
Example
export default defineConfig({bundler: 'webpack',config: (webpackConfig, { mode }) => {webpackConfig.plugins?.push(new MyPlugin());return webpackConfig;},});
Parameters
configConfigurationcontextWebpackContextContext passed to the webpack customization function.
Shaped to match argv.mode from webpack's own CLI convention. Other
bundler adapters mirror the same { mode } shape for symmetry.
modestringWhether this is a development or production build.
Available values:
"production""development"
Returns
Returns
Result of an extractTranslations run. This is a Promise that resolves with the following object:
outputDirstringDirectory where messages were written
outputFileOutputFileThe messages file written this run, with its output size
pathstringPath relative to outputDir
sizeBytesnumberSize on disk in bytes
messageCountnumberNumber of messages extracted
noticesstring[]One-line notices where an env var shadowed a config-file value.
versionstringThe running @canva/app-scripts version (the module-level version).
configPathstringAbsolute path of the loaded config file; undefined when defaults applied.