Skip to content

Latest commit

 

History

History
247 lines (167 loc) · 7.22 KB

getting-started.md

File metadata and controls

247 lines (167 loc) · 7.22 KB

Getting Started

As mentioned in the README, today Replexica works incredibly well only with Nextjs (App Router).

While we're working hard to make it work with other frameworks, let's see how to get started with Nextjs!

Tip

Before applying Replexica to your project, we recommend finishing the tutorial, to learn the basics.

Installation

First, let's create a brand new Nextjs project (be sure to choose app router when prompted):

pnpm create next-app replexica-demo
cd replexica-demo

Then, let's install Replexica:

pnpm add replexica @replexica/react @replexica/compiler

Lastly, let's login to Replexica API:

pnpm replexica auth --login

Configuration

Now, let's update the content of the next.config.mjs file to enable Replexica compiler:

// next.config.mjs

import replexica from '@replexica/compiler';

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

/** @type {import('@replexica/compiler').ReplexicaConfig} */
const replexicaConfig = {
  locale: {
    source: 'en',
    targets: ['es'],
  },
};

export default replexica.next(
  replexicaConfig,
  nextConfig,
);

Build

If you haven't already, authenticate with the Replexica platform:

pnpm replexica auth --login

Now, let's perform the initial build of our app:

pnpm run build

Next, let's process the translations using the Replexica API:

pnpm replexica i18n

Now, let's build the app again, to inject translations into the build output (Sorry for the double build, we're working on it! 🙏):

pnpm run build

Finally, let's start the app:

pnpm run start

How to authorize CLI in CI/CD

To authorize CLI in your CI/CD workflows, put your API key in an env variable called REPLEXICA_API_KEY. The API key can be found in your replexica.com dashboard.

Test

Now, let's test the app by visiting http://localhost:3000 in your browser.

You should see the app in English, at first. To quickly check that everything works, run the following code in your browser's console:

document.cookie = "REPLEXICA_LOCALE=es; path=/;";
location.reload();

... and you should see the app in Spanish!

To switch back to English, run:

document.cookie = "REPLEXICA_LOCALE=en; path=/;";
location.reload();

In the real-world scenario, you would use a language switcher to change the locale. If you need advice on how to implement it fast - send us a message in the Discord channel, and we will help!

Bonus: use client components

If you plan on having 'use client' components at least somewhere in your app, you'll need to also wrap your entire component tree in <ReplexicaProvider />.

Replace the content of the src/app/layout.tsx file with the following:

import { Inter } from "next/font/google";
import "./globals.css";
import { ReplexicaIntlProvider } from '@replexica/react/client';
import { loadLocaleFromCookie } from '@replexica/react/next';

const inter = Inter({ subsets: ["latin"] });

export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  const locale = await loadLocaleFromCookie();
  // Note the .client.json suffix of the i18n file below.
  // It means that only the values *actually used* get passed to the client, not the entire i18n dictionary.
  const localeData = await import(`@replexica/translations/${locale}.client.json`).then((m) => m.default);
  return (
    <ReplexicaIntlProvider data={localeData}>
      <html lang={locale}>
        <body className={inter.className}>{children}</body>
      </html>
    </ReplexicaIntlProvider>
  );
}

To test the use client components, let's create a new route. First, create a new file src/app/client/page.tsx with the following content:

export { default } from './content';

Then, create a new file src/app/client/content.tsx with the following content:

'use client';

export default function Content() {
  return (
    <div>
      Hello from <a href="https://react.dev/reference/react/use-client"> client component</a>!
    </div>
  );
}

As you see, there is a 'use client' directive at the top of the file. As a reminder, that means this particular component will be rendered on the client-side only, and the server will not see it, which is exactly what we want for this example.

Now, let's rebuild the app and fetch missing translations from our LLM-powered Replexica API:

pnpm run build
pnpm replexica i18n
pnpm run build

Finally, let's start the app again:

pnpm run start

Now, visit http://localhost:3000/client in your browser. You should see the use client content!

Run the following code in your browser's console to switch the locale to Spanish:

document.cookie = "REPLEXICA_LOCALE=es; path=/;";
location.reload();

and the following code to switch back to English:

document.cookie = "REPLEXICA_LOCALE=en; path=/;";
location.reload();

How to Switch Between Languages

Different apps use different strategies for switching between supported languages. Here are a few approaches we've seen:

  • Cookie value (get/set cookie value)
  • Subdomain (en.myapp.com / es.myapp.com)
  • TLD domain (myapp.com / myapp.es)
  • Pathname segments (myapp.com/en / myapp.com/es)

... and so on.

To support every possible strategy, now and in the future, Replexica does the following:

Replexica reads the value of the REPLEXICA_LOCALE cookie to determine the currently selected locale

So, whatever approach you choose for switching between locales, just be sure to update the value of the REPLEXICA_LOCALE cookie, and Replexica will handle the rest.

Warning

Be sure to drop by our Discord (link at the bottom) if you have an opinion on how Replexica should be handling the locale detection. Even if your idea is exotic or feels unfeasible, we'd love to hear it! 🙏 (feel free to send in private, if you want).

Replexica CLI

replexica auth

  • replexica auth - Check current authentication status.
  • replexica auth --login - (Re-)Authenticate with Replexica API.
  • replexica auth --logout - Log out from Replexica API.

replexica i18n

  • replexica i18n - Fetch translations from Replexica API, and save new translations to the cache.
  • replexica i18n --cache-only - Fetch translations from the cache only, and fails if some translations are missing. Useful for CI/CD workflows, when deterministic builds are required.
  • replexica i18n --skip-cache - Fetch translations from Replexica API, and rewrite the cache entirely. Useful when you want to force-fetch translations from the API.

Recognized environment variables

Replexica CLI recognizes certain environment variables, either through the .env file or through the system environment variables:

  • REPLEXICA_API_KEY - API key for Replexica API. Can be used in CI/CD workflows, as an alternative to the interactive login.

Conclusion

That's it! You've successfully set up Replexica with Nextjs!

Now that you've completed the tutorial, you can start applying Replexica to your own projects.

If you have any questions - drop them in our new Discord channel!