next-translation
Next Translation is an internationalization library for Next.js App Router.
Why one more library?
Server components are a recent feature in React. Existing translation libraries are not yet well-optimized for them. If they support it, then only by disabling Next.js static optimization.
This library is an attempt to create a highly optimized solution exclusively using the current capabilities of React.js, Next.js and node.js.
Features
Support for loading translations during page rendering (instead of the application build step), allowing for up-to-date translations with ISR or SSR;
Support for revalidation logic, i.e. you can specify how often translations should be updated (or that they should not be updated at all);
Optimized caching system - not a single extra request will be sent, even with parallel building (which is now enabled by default);
Passing only those translations to the client that are needed on the client;
Embedding parameters in client translations on the server;
Support for html entities.
Installation
Using npm:
npm i next-translationUsing yarn:
yarn add next-translationUsage
NextTranslationProvider
It is recommended to use the configuring provider at the page level.
import NextTranlationProvider from 'next-translation/NextTranlationProvider'
export default function HomePage({ params }: { params: { lang: string } }) {
return (
<NextTranlationProvider lang={params.lang} clientTerms={['shared', 'banking.about']}>
{/* ... */}
</NextTranlationProvider>
)
}Client terms will be passed to the client. You can specify both namespaces and specific keys.
Note: Layout lives independently, so it needs to be wrapped in NextTranslationProvider separately.
Server components
Use getTranslation for simple translations
import getTranslation from 'next-tranlation/getTranslation';
const ServerComponent: React.FC = () => {
const { t } = getTranslation();
return (
<div>
{/* Welcome to Next Translation */}
{t('header.nav.home')}
</div>
)
}Use ServerTranslation to get complex translations
import ServerTranslation from 'next-tranlation/ServerTranslation';
const ServerComponent: React.FC = () => (
<ServerTranslation
term='intro.description' // We have {{number}} tariffs. Read more about pricings <link>special section</link>
components={{
link: <a href='#' />
}}
query={{ number: 5 }}
/>
)Client components
The translations specified in NextTranslationProvider are passed to the client, but you can specify additional translations in any parent server component using NextTranslationTransmitter.
You can specify both namespaces and specific keys.
import NextTranslationTransmitter from 'next-tranlation/NextTranslationTransmitter';
import ClientComponent from './ClientComponent';
const ServerComponent: React.FC = () => (
<NextTranslationTransmitter terms={['header.nav']}>
<ClientComponent />
</NextTranslationTransmitter>
)Use useTranslation for simple translations
"use client";
import useTranslation from 'next-tranlation/useTranslation';
const ClientComponent: React.FC = () => {
const { t } = useTranslation();
return (
<div>
{/* Welcome to Next Translation */}
{t('header.nav.home')}
</div>
)
}Use ClientTranslation for complex translations
"use client";
import ClientTranslation from 'next-tranlation/ClientTranslation';
const ClientComponent: React.FC = () => (
<ClientTranslation
term='intro.description' // We have {{number}} tariffs. Read more about pricings <link>special section</link>
components={{
link: <a href='#' />
}}
query={{ number: 5 }}
/>
)Other
Use createTranslation to get a simple translation outside the page tree.
import createTranslation from 'next-translation/createTranslation'
// ...
export async function generateMetadata({ params }: { params: { lang: string } }) {
const { t } = await createTranslation(params.lang);
return {
title: t('homePage.meta.title'),
}
}Options
You can pass opts as the second argument of t.
Now you can pass a query there to inject variable strings inside translations.
const Component: React.FC = () => {
return (
<div>
{/* Price starts from ${{price}} */}
{t('pricing.tariffs.solo', { query: { price: 16.99 } })}
</div>
)
}Also you can inject query to client terms on the server side. For example, when they depend on the server environment or when you get values from a database on the server.
Just add an array value instead of a string in terms arr, where the second element will be the query object.
import NextTranslationTransmitter from 'next-tranlation/NextTranslationTransmitter';
import ClientComponent from './ClientComponent';
const ServerComponent: React.FC = () => (
<NextTranslationTransmitter terms={[['home.welcome', { stage: process.env.GITHUB_REF === 'main' ? 'production' : 'test' }]]}>
<ClientComponent />
</NextTranslationTransmitter>
)Configuration
Config file
Create next-translation.js file in the root directory
/** @type {import('next-translation/configuration/types').Config} */
module.exports = {
load: async (lang) => {
const resp = await fetch(`https://api.translation-example.com/terms/${lang}`, {
method: 'POST',
});
const data = await resp.json();
return { data, meta: {} };
},
languages: ['en', 'de', 'fr'],
revalidate: 3600,
checkIsActual: async (lang, lastLoadMeta) => {
// ...
},
retryAttempts: 2,
};Options
load [required]
Asynchronous function for translates loading.
Function will receive 2 arguments:
key - current language;
meta - meta data from previous request.
Function should return object with keys:
data - object with translates;
meta - object with additional data which will be passed to the next load.
Don't combine next.js fetch caching with the next-translation load caching, it will repeat the logic and may not work correctly.
languages [required]
Array of allowed languages. Languages outside of this array will be ignored.
revalidate [optional]
Option works similarly to the next.js option. Setting it to false will disable revalidation, meaning the data will be cached indefinitely. Setting it to 0 will request the data each time, while setting it to a number will determine the time in seconds for revalidation to occur.
retryAttempts [optional]
Number of retries when loading data (3 by default)
checkIsActual [optional]
Check that the data is up to date. Use it when you can perform additional steps to ensure that cached data is up to date. For example, make a HEAD request with meta information, or check the meta on a different route. Option type:
(key: string, meta?: { [key: string]: string }) => Promise<boolean>
where:
key - target language
meta - meta information returned from the load function
Configure app
You also need to configure the environment for correct caching to work, for this you need to wrap your next.config.js in withNextTranslation
const withNextTranslation = require('next-translation/withNextTranslation').default;
/** @type {import('next').NextConfig} */
const nextConfig = {};
module.exports = async (phase) => {
const withTranslation = await withNextTranslation(phase);
return withTranslation(nextConfig);
}Note: the library does not modify the webpack or application configuration, it only configures the process.
App organization
Pages structure
app
[lang]
page-name
page.tsx
page.tsx
layout.tsx
(root)
page-name
page.tsx
page.tsx
layout.tsx
Why so?
You can only create one root layout. In the root (/app) we don't know the language, so we can't add a lang attribute there on the server side.
Therefore, the only way to do it is to create a root layout for localized pages in the [lang] folder.
// /app/[lang]/layout.tsx
type RootLayoutProps = { children: React.ReactNode; params: { lang: string } }
export default function RootLayout({ children, params }: RootLayoutProps) {
return (
<html lang={params.lang}>
<body>{children}</body>
</html>
)
}Additionally
Create tasks with wishes, ideas, difficulties, etc. All of them will definitely be considered and thought over.