feat: add fallback locale (#14)

* feat: add fallback locale

* chore(docs): add example about fallback locale

* test: add tests for fallback locales

Author: QuiiBz

examples/next/locales/en.ts

@@ -8,4 +8,5 @@ export default {
   'scope.more.test': 'A scope',
   'scope.more.param': 'A scope with {param}',
   'scope.more.and.more.test': 'A scope',
+  'missing.translation.in.fr': 'This should work',
 } as const;

examples/next/locales/fr.ts

@@ -10,4 +10,5 @@ export default defineLocale({
   'scope.more.test': 'Un scope',
   'scope.more.param': 'Un scope avec un {param}',
   'scope.more.and.more.test': 'Un scope',
+  'missing.translation.in.fr': '', // Comment to test locale fallback
 });

examples/next/pages/_app.tsx

@@ -1,10 +1,11 @@
 import React from 'react';
 import { AppProps } from 'next/app';
 import { I18nProvider } from '../locales';
+import en from '../locales/en';
 
 const App = ({ Component, pageProps }: AppProps) => {
   return (
-    <I18nProvider locale={pageProps.locale} fallback={<p>Loading initial locale client-side</p>}>
+    <I18nProvider locale={pageProps.locale} fallback={<p>Loading initial locale client-side</p>} fallbackLocale={en}>
       <Component {...pageProps} />
     </I18nProvider>
   );

examples/next/pages/index.tsx

@@ -30,6 +30,7 @@ const Home = () => {
         })}
       </p>
       <p>{t2('and.more.test')}</p>
+      <p>{t('missing.translation.in.fr')}</p>
       <button type="button" onClick={() => changeLocale('en')}>
         EN
       </button>

packages/next-international/README.md

@@ -15,6 +15,7 @@
 - [Examples](#examples)
   - [Scoped translations](#scoped-translations)
   - [Change current locale](#change-current-locale)
+  - [Fallback locale for missing translations](#fallback-locale-for-missing-translations)
   - [Use JSON files instead of TS for locales](#use-json-files-instead-of-ts-for-locales)
   - [Explicitly typing the locales](#explicitly-typing-the-locales)
   - [Load initial locales client-side](#load-initial-locales-client-side)
@@ -163,6 +164,22 @@ function App() {
 }
 ```
 
+### Fallback locale for missing translations
+
+It's common to have missing translations in an application. By default, next-international outputs the key when no translation is found for the current locale, to avoid sending to users uncessary data.
+
+You can provide a fallback locale that will be used for all missing translations:
+
+```tsx
+// pages/_app.tsx
+import { I18nProvider } from '../locales'
+import en from '../locales/en'
+
+<I18nProvider locale={pageProps.locale} fallbackLocale={en}>
+  ...
+</I18nProvider>
+```
+
 ### Use JSON files instead of TS for locales
 
 Currently, this breaks the parameters type-safety, so we recommend using the TS syntax. See this issue: https://github.com/microsoft/TypeScript/issues/32063.

packages/next-international/__tests__/fallback-locale.test.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createI18n } from '../src';
+import { render, screen } from './utils';
+import en from './utils/en';
+import fr from './utils/fr';
+
+beforeEach(() => {
+  vi.mock('next/router', () => ({
+    useRouter: vi.fn().mockImplementation(() => ({
+      locale: 'fr',
+      defaultLocale: 'fr',
+      locales: ['en', 'fr'],
+    })),
+  }));
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('fallbackLocale', () => {
+  it('should output the key when no fallback locale is configured', async () => {
+    const { useI18n, I18nProvider } = createI18n<typeof import('./utils/en').default>({
+      en: () => import('./utils/en'),
+      fr: () => import('./utils/fr'),
+    });
+
+    function App() {
+      const { t } = useI18n();
+
+      return <p>{t('only.exists.in.en')}</p>;
+    }
+
+    render(
+      // @ts-expect-error missing key
+      <I18nProvider locale={fr}>
+        <App />
+      </I18nProvider>,
+    );
+
+    expect(screen.getByText('only.exists.in.en')).toBeInTheDocument();
+  });
+
+  it('should output the key when no fallback locale is configured', async () => {
+    const { useI18n, I18nProvider } = createI18n<typeof import('./utils/en').default>({
+      en: () => import('./utils/en'),
+      fr: () => import('./utils/fr'),
+    });
+
+    function App() {
+      const { t } = useI18n();
+
+      return <p>{t('only.exists.in.en')}</p>;
+    }
+
+    render(
+      // @ts-expect-error missing key
+      <I18nProvider locale={fr} fallbackLocale={en}>
+        <App />
+      </I18nProvider>,
+    );
+
+    expect(screen.getByText('EN locale')).toBeInTheDocument();
+  });
+});

packages/next-international/__tests__/utils/en.ts

@@ -8,4 +8,5 @@ export default {
   'namespace.subnamespace.hello.world': 'Hello World!',
   'namespace.subnamespace.weather': "Today's weather is {weather}",
   'namespace.subnamespace.user.description': '{name} is {years} years old',
+  'only.exists.in.en': 'EN locale',
 } as const;

packages/next-international/src/i18n/create-i18n-provider.tsx

@@ -6,14 +6,20 @@ import { error, warn } from '../helpers/log';
 type I18nProviderProps<Locale extends BaseLocale> = {
   locale: Locale;
   fallback?: ReactElement | null;
+  fallbackLocale?: Locale;
   children: ReactNode;
 };
 
 export function createI18nProvider<Locale extends BaseLocale>(
   I18nContext: Context<LocaleContext<Locale> | null>,
   locales: Locales,
 ) {
-  return function I18nProvider({ locale: baseLocale, fallback = null, children }: I18nProviderProps<Locale>) {
+  return function I18nProvider({
+    locale: baseLocale,
+    fallback = null,
+    fallbackLocale,
+    children,
+  }: I18nProviderProps<Locale>) {
     const { locale, defaultLocale, locales: nextLocales } = useRouter();
     const [clientLocale, setClientLocale] = useState<Locale>();
 
@@ -63,6 +69,7 @@ export function createI18nProvider<Locale extends BaseLocale>(
       <I18nContext.Provider
         value={{
           localeContent: clientLocale || baseLocale,
+          fallbackLocale,
         }}
       >
         {children}

packages/next-international/src/i18n/create-use-i18n.ts

@@ -23,9 +23,13 @@ export function createUsei18n<Locale extends BaseLocale>(I18nContext: Context<Lo
         Key extends LocaleKeys<Locale, Scope>,
         Value extends LocaleValue = ScopedValue<Locale, Scope, Key>,
       >(key: Key, ...params: Params<Value>['length'] extends 0 ? [] : [ParamsObject<Value>]) {
-        const { localeContent } = context as LocaleContext<Locale>;
+        const { localeContent, fallbackLocale } = context as LocaleContext<Locale>;
 
-        let value = ((scope ? localeContent[`${scope}.${key}`] : localeContent[key]) || key).toString();
+        let value = (
+          (scope ? localeContent[`${scope}.${key}`] : localeContent[key]) ||
+          (scope ? fallbackLocale?.[`${scope}.${key}`] : fallbackLocale?.[key]) ||
+          key
+        ).toString();
         const paramObject = params[0];
 
         if (!paramObject) {

packages/next-international/src/types.ts

@@ -11,6 +11,7 @@ export type Locales = Record<string, () => Promise<any>>;
 
 export type LocaleContext<Locale extends BaseLocale> = {
   localeContent: Locale;
+  fallbackLocale?: Locale;
 };
 
 export type Params<Value extends LocaleValue> = Value extends ''