# Vue & Nuxt localization with TransLocale

Work with Vue I18n catalogs in Vue 3, or connect them to Nuxt's locale routing and server rendering.

Canonical page: https://translocale.io/integrations/vue

## Install

@translocale/vue 0.1.9. Node.js 22.16+. Message format: Vue I18n JSON.

```bash
npm install @translocale/vue vue-i18n
```

## Connect and configure

Create a cloud project under Projects → New project. Copy PROJECT_UUID from Project settings → Credentials, and match the project languages to your catalogs. Browser login stores authoring access outside the app. For CI, create a credential under Project settings → Credentials and put it in the TRANSLOCALE_TOKEN secret. App delivery uses a separate read-only credential under Releases → App delivery.

```bash
npx translocale-vue init --api https://translocale.io --project PROJECT_UUID --locales en,fr,ja
```

```bash
npx translocale-vue login --scope translate
```

Vue setup generates src/translocale-i18n.ts. Register its createTransLocaleI18n(locale) factory with your app. For Nuxt, install @nuxtjs/i18n and add --framework nuxt to init instead; use createNuxtI18nOptions from @translocale/vue/nuxt in nuxt.config.ts. The included README has the complete Nuxt configuration. Download all target catalogs before building.

## Translate and review

Inspect the plan before translating. The translate example starts a job capped at 1,000 source characters across target languages. Replace JOB_UUID with its returned ID. Save and review revision 1 before pulling it, or choose the exact revision you want to ship. Repeat pull for each target language. Normal builds do not start translation jobs.

```bash
npx translocale-vue plan
npx translocale-vue translate --max-characters 1000 --wait
npx translocale-vue pull --job JOB_UUID --locale fr --revision 1
npx translocale-vue check
```

Run npx translocale-vue discover --source en to find existing JSON catalogs. Nuxt uses the same discovery and sync commands. Sync shows local and incoming changes against the recorded revision and keeps recovery copies when you apply a reviewed update.

## Project setup and credentials

The screenshot walkthrough covers project creation, catalog import, keys, review, releases, and credentials. Use this framework’s message format and catalog identities. Authoring tokens belong in developer tools and CI; app delivery credentials only read published wording. Flutter’s flutter-connect writes DELIVERY_* build settings, while the dashboard download uses projectId, channel, schemaHash, deliveryToken, and apiBaseUrl.

- [Follow the illustrated first-project guide](https://translocale.io/docs/getting-started)

## Change the language in Vue I18n

Use the global composer when a language switch should update the whole Vue app. With the generated createTransLocaleI18n factory registered through app.use(), the component below binds its selector to that composer's locale. Both languages must have local catalog files and appear in translocale.config.json.

locales/en.json:

```json
{
  "welcome": "Hello, {name}",
  "items": "No items | One item | {count} items"
}
```

locales/fr.json:

```json
{
  "welcome": "Bonjour, {name}",
  "items": "Aucun article | Un article | {count} articles"
}
```

LanguageSwitcher.vue:

```text
<script setup>
import {useI18n} from 'vue-i18n';
const {t, locale} = useI18n({useScope: 'global'});
</script>

<template>
  <label>
    Language
    <select v-model="locale">
      <option value="en">English</option>
      <option value="fr">Français</option>
    </select>
  </label>
  <p>{{ t('welcome', {name: 'Sam'}) }}</p>
  <p>{{ t('items', 3) }}</p>
</template>
```

Selecting Français changes the greeting to “Bonjour, Sam” and the count to “3 articles”. If only one component changes language, check whether it created a local composer. useScope: 'global' selects the app's composer. In script code, assign locale.value; Vue templates unwrap the ref for v-model.

Create a fresh i18n instance for each server-rendered app. The generated factory copies the catalogs for each call. Keep the Node.js package entry point in developer tooling; browser components import Vue I18n and the generated module.

- [Vue I18n scope and locale changes](https://vue-i18n.intlify.dev/guide/essentials/scope)

## Load JSON translation files in Nuxt

Nuxt uses the same Vue I18n JSON catalogs, with @nuxtjs/i18n responsible for loading them and routing between languages. Install the module, then initialize with the Nuxt option from your app directory. For an existing TransLocale configuration, review its locale list and file pattern instead of initializing again.

Initialize Nuxt catalog tooling:

```bash
npm install @translocale/vue vue-i18n @nuxtjs/i18n
npx translocale-vue init --framework nuxt --api https://translocale.io --project PROJECT_UUID --source en --locales en,fr
```

The default files pattern is locales/{locale}.json. Supply both example files above before starting Nuxt. Setup creates a source file if missing; it does not generate target translations. Keep your existing Nuxt options and add the module configuration below.

nuxt.config.ts:

```text
import {fileURLToPath} from 'node:url';
import {createNuxtI18nOptions} from '@translocale/vue/nuxt';

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: createNuxtI18nOptions({
    root: fileURLToPath(new URL('.', import.meta.url)),
  }),
});
```

The helper reads translocale.config.json from root, checks every configured catalog, and returns project-relative paths such as locales/fr.json. It sets restructureDir and langDir to '.' to preserve those paths. If a file cannot be found, compare the configured files pattern with its actual path and confirm root points to the Nuxt app.

The default routing strategy is prefix_except_default: English is unprefixed and French routes use /fr. Browser-language redirection is disabled by this helper. For route-aware language changes, use Nuxt's setLocale API instead of assigning the Vue locale ref directly.

Switch to the French route in Nuxt:

```text
<script setup>
const {setLocale} = useI18n();
</script>

<template>
  <button type="button" @click="setLocale('fr')">Français</button>
</template>
```

Check before starting or building:

```bash
npx translocale-vue check
```

A missing French file or a changed {name} placeholder stops the catalog check. Restore the file or placeholder and repeat it. Local checks and builds need no TransLocale credential and do not start translation jobs. Custom plural rules and catalogs embedded in .vue files remain outside this adapter's supported format.

- [Nuxt language switching](https://i18n.nuxtjs.org/docs/guide/lang-switcher)
- [Check one Vue I18n source file](https://translocale.io/app)
- [JSON format examples](https://translocale.io/docs#json-translation-examples)

## Compatibility and further setup

Use Vue I18n 11.4.x with the default plural rules. Custom compilers, custom plural rules, and catalogs embedded in .vue components are not supported.

Nuxt server rendering and hydration have been tested in local Cloudflare. Hosted consumers, Nuxt layers, and domain-based routing still need verification.

- [Complete framework guide, including runtime examples](https://translocale.io/integrations/vue)
- [MCP guide](https://translocale.io/docs/mcp)
- [Free source file checker](https://translocale.io/app)