​
Create a Quetzal Project

First, sign up for Quetzal here.

You will then be prompted to create a New Quetzal Project.

Quetzal is currently free to use for one language

​
Install Quetzal

Once your project is created, install our npm package to set up your Node.js project with Quetzal.

npm install --save @quetzallabs/i18n

Don’t see an option that works for you? Contact Us if you are unsure of how to set up Quetzal with your stack

After installing, run the setup script:

npx quetzal-setup

This script will do the following:

  1. Makes a change to your .env file so you can add your Quetzal API Key
  2. Adds a template quetzal.config.json file for you to edit
  3. Adds our locale detector (i18n.ts) in your project root which detect’s the user’s locale for use with next-intl
  4. Adds a “prebuild” script to your package.json so that we can get all your strings before a build and either get the existing translations or translate new strings.

​
Next-Intl Setup

Quetzal is built on next-intl for Next.js apps and use-intl for React apps.

As such, you must update your app to use the NextIntlClientProvider or IntlProvider.

For Next projects, you also must include the createNextIntlPlugin in your next config file. This process is documented by next-intl.

​
Optional: Install VSCode/Cursor Extension

To dramatically speed up integration throughout your app, install the Quetzal VSCode Extension

​
Continue setting up your project

As mentioned above, you should do the following before continuing:

  1. Update your .env file with your QUETZAL_API_KEY found in the dashboard from the previous step. (If you used the setup script, this will already be added for you!)
  2. Modify the quetzal.config.json specifying which folders to scrape for t-wrapped strings.
  3. Update next.config.js or next.config.mjs to add the next-intl plugin to your project:

next.config.js

const createNextIntlPlugin = require('next-intl/plugin');

const withNextIntl = createNextIntlPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {};

module.exports = withNextIntl(nextConfig);

next.config.mjs

import createNextIntlPlugin from 'next-intl/plugin';

const withNextIntl = createNextIntlPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withNextIntl(nextConfig);
  1. Add the next-intl provider to your layout.tsx, like so:
import {NextIntlClientProvider} from 'next-intl';
import {getLocale, getMessages} from 'next-intl/server';

export default async function RootLayout({
  children
}: {
  children: React.ReactNode;
}) {
  const locale = await getLocale();

  // Providing all messages to the client
  // side is the easiest way to get started
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

​
Usage

Now you can use the t function from either the hook or the awaitable function like so:

Async/Server Components

import { getI18nUtils } from "@quetzallabs/i18n";

export default async function Home() {
    const { t } = await getI18nUtils();
    return <p>{t("The text of my string here")}</p>;
}

Client Components

import { useI18n } from "@quetzallabs/useI18n";

export default function Home() {
    const { t } = useI18n();
    return <p>{t("The text of my string here")}</p>;
}

See more information about how to use the t function here.

​
Wrapping Strings for Translation

To find the strings to translate, you can use our VSCode Extension to find all of your user-facing strings. This extension was installed as a part of the setup script. To use it:

  1. Open VSCode
  2. Press Cmd+Shift+P
  3. Type “Quetzal” and find “Quetzal: Scan for user-facing strings”
  4. Select filetypes and folders to scan for strings
  5. Now you can see every file that has user-facing strings and easily wrap them appropriately

You can also use this VSCode extension on a specific file.

​
Running translations

To manually submit strings for translation, run npm run prebuild. This will scrape all of the strings you wrapped in the previous step and send them to us for translation. This will also run when you run npm run build. You can see the status of these translations on the Quetzal dashboard. For a few strings, it should only take a second. For many hundreds or thousands of strings, it may take a few minutes.

And now you’re done! Strings will be grabbed and translated when production builds are made going forward.