Skip to main content
Unlock powerful debugging and effortless query monitoring with Refine DevtoolsLearn More
RefineDocumentation
Version: 4.xx.xx

Internationalization (i18n)

Internationalization (i18n) is a process that allows software applications to be localized for different regions and languages. Refine can work with any i18n framework, but needs an i18nProvider to be created based on the chosen library.

i18n Provider​

i18nProvider centralizes localization process in Refine applications. With flexible interface you can use any i18n library you want.

Here is the basic example i18nProvider with react-i18next. We will explain the details in the following sections.

import React from "react";
import { useTranslation } from "@refinedev/core";

export const HomePage = () => {
    const { translate, getLocale, changeLocale } = useTranslation();

    return (
        <div>
            <h1>{translate("page.home.title")}</h1>
            <select
                value={getLocale()}
                onChange={(e) => changeLanguage(e.target.value)}
            >
                <option value="en">English</option>
                <option value="de">German</option>
            </select>
        </div>
    );
};
Open on CodeSandboxOpen Sandbox

Example​

Good to know:
  • We will use the Ant Design UI library in this example. You can use any UI library you want.
  • We recommend using create refine-app to initialize your Refine projects as it configures the project according to your needs, i18n support included if you choose it in the CLI
  • For more information, refer to the react-i18next documentation→
  • This example is for SPA react apps, for Next.js refer to i18n Next.js example→

First of all, Refine expects the i18nProvider type as follows:

import { I18nProvider } from "@refinedev/core";

const i18nProvider: I18nProvider = {
  translate: (key: string, options?: any, defaultMessage?: string) => string,
  changeLocale: (lang: string, options?: any) => Promise,
  getLocale: () => string,
};

After creating a i18nProvider, you can pass it to the <Refine /> component:

src/App.tsx
import { Refine } from "@refinedev/core";

import i18nProvider from "./i18nProvider";

const App: React.FC = () => {
  return (
    <Refine
      i18nProvider={i18nProvider}
      /* ... */
    >
      {/* ... */}
    </Refine>
  );
};

This will allow us to put translation features to the useTranslation hook

Let's add multi-language support to our application using the react-i18next framework. When we are done, our application will support both German and English.

Installation​

To install both react-i18next and i18next packages, run the following command within your project directory:

npm i react-i18next i18next i18next-http-backend i18next-browser-languagedetector

Creating the i18n Instance​

First, we will create an i18n instance using react-i18next.

src/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next"; // https://react.i18next.com/latest/using-with-hooks
import Backend from "i18next-http-backend"; // For lazy loading for translations: https://github.com/i18next/i18next-http-backend
import detector from "i18next-browser-languagedetector"; // For auto detecting the user language: https://github.com/i18next/i18next-browser-languageDetector

i18n
  .use(Backend)
  .use(detector)
  .use(initReactI18next)
  .init({
    supportedLngs: ["en", "de"],
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json", // locale files path
    },
    ns: ["common"],
    defaultNS: "common",
    fallbackLng: ["en", "de"],
  });

export default i18n;

Wrapping the app with React.Suspense​

Then we will import the i18n instance we created and wrap the application with React.Suspense.

src/index.tsx
import React from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

import "./i18n";

const container = document.getElementById("root");
const root = createRoot(container!);
root.render(
  <React.StrictMode>
    <React.Suspense fallback="loading">
      <App />
    </React.Suspense>
  </React.StrictMode>,
);

Creating the i18n Provider​

Next, we will include the i18n instance and create the i18nProvider using react-i18next.

src/App.tsx
import type { I18nProvider } from "@refinedev/core";
import { Refine } from "@refinedev/core";
import { useTranslation } from "react-i18next";

const App: React.FC = () => {
  const { t, i18n } = useTranslation();

  const i18nProvider: I18nProvider = {
    translate: (key: string, options?: any) => t(key, options),
    changeLocale: (lang: string) => i18n.changeLanguage(lang),
    getLocale: () => i18n.language,
  };

  return (
    <Refine
      i18nProvider={i18nProvider}
      /* ... */
    >
      {/* ... */}
    </Refine>
  );
};

After we pass the i18nProvider to the <Refine /> component, useTranslation hook will be ready for use.

Adding the Translations Files​

Before we get started, let's look at which parts are going to be translated:

The translation file
/locales/en/common.json
{
  "pages": {
    "login": {
      "title": "Sign in to your account",
      "signin": "Sign in",
      "signup": "Sign up",
      "divider": "or",
      "fields": {
        "email": "Email",
        "password": "Password"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required",
        "requiredPassword": "Password is required"
      },
      "buttons": {
        "submit": "Login",
        "forgotPassword": "Forgot password?",
        "noAccount": "Don’t have an account?",
        "rememberMe": "Remember me"
      }
    },
    "forgotPassword": {
      "title": "Forgot your password?",
      "fields": {
        "email": "Email"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required"
      },
      "buttons": {
        "submit": "Send reset instructions"
      }
    },
    "register": {
      "title": "Sign up for your account",
      "fields": {
        "email": "Email",
        "password": "Password"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required",
        "requiredPassword": "Password is required"
      },
      "buttons": {
        "submit": "Register",
        "haveAccount": "Have an account?"
      }
    },
    "updatePassword": {
      "title": "Update password",
      "fields": {
        "password": "New Password",
        "confirmPassword": "Confirm new password"
      },
      "errors": {
        "confirmPasswordNotMatch": "Passwords do not match",
        "requiredPassword": "Password required",
        "requiredConfirmPassword": "Confirm password is required"
      },
      "buttons": {
        "submit": "Update"
      }
    },
    "error": {
      "info": "You may have forgotten to add the {{action}} component to {{resource}} resource.",
      "404": "Sorry, the page you visited does not exist.",
      "resource404": "Are you sure you have created the {{resource}} resource.",
      "backHome": "Back Home"
    }
  },
  "actions": {
    "list": "List",
    "create": "Create",
    "edit": "Edit",
    "show": "Show"
  },
  "buttons": {
    "create": "Create",
    "save": "Save",
    "logout": "Logout",
    "delete": "Delete",
    "edit": "Edit",
    "cancel": "Cancel",
    "confirm": "Are you sure?",
    "filter": "Filter",
    "clear": "Clear",
    "refresh": "Refresh",
    "show": "Show",
    "undo": "Undo",
    "import": "Import",
    "clone": "Clone",
    "notAccessTitle": "You don't have permission to access"
  },
  "warnWhenUnsavedChanges": "Are you sure you want to leave? You have unsaved changes.",
  "notifications": {
    "success": "Successful",
    "error": "Error (status code: {{statusCode}})",
    "undoable": "You have {{seconds}} seconds to undo",
    "createSuccess": "Successfully created {{resource}}",
    "createError": "There was an error creating {{resource}} (status code: {{statusCode}})",
    "deleteSuccess": "Successfully deleted {{resource}}",
    "deleteError": "Error when deleting {{resource}} (status code: {{statusCode}})",
    "editSuccess": "Successfully edited {{resource}}",
    "editError": "Error when editing {{resource}} (status code: {{statusCode}})",
    "importProgress": "Importing: {{processed}}/{{total}}"
  },
  "loading": "Loading",
  "tags": {
    "clone": "Clone"
  },
  "dashboard": {
    "title": "Dashboard"
  },
  "posts": {
    "posts": "Posts",
    "fields": {
      "id": "Id",
      "title": "Title",
      "category": "Category",
      "status": {
        "title": "Status",
        "published": "Published",
        "draft": "Draft",
        "rejected": "Rejected"
      },
      "content": "Content",
      "createdAt": "Created At"
    },
    "titles": {
      "create": "Create Post",
      "edit": "Edit Post",
      "list": "Posts",
      "show": "Show Post"
    }
  },
  "table": {
    "actions": "Actions"
  },
  "documentTitle": {
    "default": "refine",
    "suffix": " | Refine",
    "post": {
      "list": "Posts | Refine",
      "show": "#{{id}} Show Post | Refine",
      "edit": "#{{id}} Edit Post | Refine",
      "create": "Create new Post | Refine",
      "clone": "#{{id}} Clone Post | Refine"
    }
  },
  "autoSave": {
    "success": "saved",
    "error": "auto save failure",
    "loading": "saving...",
    "idle": "waiting for changes"
  }
}

Now, let's add the language files:

|-- public
|   |-- locales
|       |-- en
|       |   |-- common.json
|       |-- de
|           |-- common.json
|-- src
|-- package.json
|-- tsconfig.json
Show translation file
/locales/en/common.json
{
  "pages": {
    "login": {
      "title": "Sign in to your account",
      "signin": "Sign in",
      "signup": "Sign up",
      "divider": "or",
      "fields": {
        "email": "Email",
        "password": "Password"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required",
        "requiredPassword": "Password is required"
      },
      "buttons": {
        "submit": "Login",
        "forgotPassword": "Forgot password?",
        "noAccount": "Don’t have an account?",
        "rememberMe": "Remember me"
      }
    },
    "forgotPassword": {
      "title": "Forgot your password?",
      "fields": {
        "email": "Email"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required"
      },
      "buttons": {
        "submit": "Send reset instructions"
      }
    },
    "register": {
      "title": "Sign up for your account",
      "fields": {
        "email": "Email",
        "password": "Password"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required",
        "requiredPassword": "Password is required"
      },
      "buttons": {
        "submit": "Register",
        "haveAccount": "Have an account?"
      }
    },
    "updatePassword": {
      "title": "Update password",
      "fields": {
        "password": "New Password",
        "confirmPassword": "Confirm new password"
      },
      "errors": {
        "confirmPasswordNotMatch": "Passwords do not match",
        "requiredPassword": "Password required",
        "requiredConfirmPassword": "Confirm password is required"
      },
      "buttons": {
        "submit": "Update"
      }
    },
    "error": {
      "info": "You may have forgotten to add the {{action}} component to {{resource}} resource.",
      "404": "Sorry, the page you visited does not exist.",
      "resource404": "Are you sure you have created the {{resource}} resource.",
      "backHome": "Back Home"
    }
  },
  "actions": {
    "list": "List",
    "create": "Create",
    "edit": "Edit",
    "show": "Show"
  },
  "buttons": {
    "create": "Create",
    "save": "Save",
    "logout": "Logout",
    "delete": "Delete",
    "edit": "Edit",
    "cancel": "Cancel",
    "confirm": "Are you sure?",
    "filter": "Filter",
    "clear": "Clear",
    "refresh": "Refresh",
    "show": "Show",
    "undo": "Undo",
    "import": "Import",
    "clone": "Clone",
    "notAccessTitle": "You don't have permission to access"
  },
  "warnWhenUnsavedChanges": "Are you sure you want to leave? You have unsaved changes.",
  "notifications": {
    "success": "Successful",
    "error": "Error (status code: {{statusCode}})",
    "undoable": "You have {{seconds}} seconds to undo",
    "createSuccess": "Successfully created {{resource}}",
    "createError": "There was an error creating {{resource}} (status code: {{statusCode}})",
    "deleteSuccess": "Successfully deleted {{resource}}",
    "deleteError": "Error when deleting {{resource}} (status code: {{statusCode}})",
    "editSuccess": "Successfully edited {{resource}}",
    "editError": "Error when editing {{resource}} (status code: {{statusCode}})",
    "importProgress": "Importing: {{processed}}/{{total}}"
  },
  "loading": "Loading",
  "tags": {
    "clone": "Clone"
  },
  "dashboard": {
    "title": "Dashboard"
  },
  "posts": {
    "posts": "Posts",
    "fields": {
      "id": "Id",
      "title": "Title",
      "category": "Category",
      "status": {
        "title": "Status",
        "published": "Published",
        "draft": "Draft",
        "rejected": "Rejected"
      },
      "content": "Content",
      "createdAt": "Created At"
    },
    "titles": {
      "create": "Create Post",
      "edit": "Edit Post",
      "list": "Posts",
      "show": "Show Post"
    }
  },
  "table": {
    "actions": "Actions"
  },
  "documentTitle": {
    "default": "refine",
    "suffix": " | Refine",
    "post": {
      "list": "Posts | Refine",
      "show": "#{{id}} Show Post | Refine",
      "edit": "#{{id}} Edit Post | Refine",
      "create": "Create new Post | Refine",
      "clone": "#{{id}} Clone Post | Refine"
    }
  },
  "autoSave": {
    "success": "saved",
    "error": "auto save failure",
    "loading": "saving...",
    "idle": "waiting for changes"
  }
}

All of Refine's components support i18n, meaning that if you want to change their text, you can create your own translation files with the reference to the keys above. We can override Refine's default texts by changing the common.json files in the example above.

Changing The Locale​

Next, we will create a <Header /> component. This component will allow us to change the language.

src/components/header.tsx
import { DownOutlined } from "@ant-design/icons";
import { useTranslation } from "@refinedev/core";
import { Avatar, Button, Dropdown, Layout, Menu, Space } from "antd";
import { useTranslation } from "react-i18next";

export const Header: React.FC = () => {
  const { i18n } = useTranslation();
  const { getLocale, changeLocale } = useTranslation();
  const currentLocale = getLocale();

  const menu = (
    <Menu selectedKeys={currentLocale ? [currentLocale] : []}>
      {[...(i18n.languages || [])].sort().map((lang: string) => (
        <Menu.Item
          key={lang}
          onClick={() => changeLocale(lang)}
          icon={
            <span style={{ marginRight: 8 }}>
              <Avatar size={16} src={`/images/flags/${lang}.svg`} />
            </span>
          }
        >
          {lang === "en" ? "English" : "German"}
        </Menu.Item>
      ))}
    </Menu>
  );

  return (
    <Layout.Header
      style={{
        display: "flex",
        justifyContent: "flex-end",
        alignItems: "center",
        padding: "0px 24px",
        height: "48px",
        backgroundColor: "#FFF",
      }}
    >
      <Dropdown overlay={menu}>
        <Button type="link">
          <Space>
            <Avatar size={16} src={`/images/flags/${currentLocale}.svg`} />
            {currentLocale === "en" ? "English" : "German"}
            <DownOutlined />
          </Space>
        </Button>
      </Dropdown>
    </Layout.Header>
  );
};

Then, we will pass <Header> to our <Layout> component.

src/App.tsx
import { Refine, Resource } from "@refinedev/core";
import { ThemedLayoutV2 } from "@refinedev/antd";

import { useTranslation } from "react-i18next";

import "./i18n";

import { Header } from "components";

const App: React.FC = () => {
    const { t, i18n } = useTranslation();

    const i18nProvider = {
        translate: (key: string, options?: any) => t(key, options),
        changeLocale: (lang: string) => i18n.changeLanguage(lang),
        getLocale: () => i18n.language,
    };

    return (
        <Refine
            i18nProvider={i18nProvider}
            /* ... */
        >
            <ThemedLayoutV2
                header={<Header />}
            >
                {/* ... */}
            </Layout>
        </Refine>
    );
};

Finally, we will create the <PostList> page and then we will translate texts using useTranslation.

src/App.tsx
import {
  useTranslation,
  useMany,
} from "@refinedev/core";
import {
  List,
  useTable,
  TextField,
  EditButton,
  ShowButton,
} from "@refinedev/antd";
import { Table, Space } from "antd";

import { IPost, ICategory } from "interfaces";

export const PostList: React.FC = () => {
  const { translate } = useTranslation();
  const { tableProps } = useTable<IPost>();

  const categoryIds =
    tableProps?.dataSource?.map((item) => item.category.id) ?? [];
  const { data, isLoading } = useMany<ICategory>({
    resource: "categories",
    ids: categoryIds,
    queryOptions: {
      enabled: categoryIds.length > 0,
    },
  });

  return (
    <List>
      <Table {...tableProps} rowKey="id">
        <Table.Column dataIndex="id" title="ID" />
        <Table.Column
          dataIndex="title"
          title={translate("posts.fields.title")}
        />
        <Table.Column
          dataIndex={["category", "id"]}
          title={translate("posts.fields.category")}
          render={(value) => {
            if (isLoading) {
              return <TextField value="Loading..." />;
            }

            return (
              <TextField
                value={data?.data.find((item) => item.id === value)?.title}
              />
            );
          }}
        />
        <Table.Column<IPost>
          title={translate("table.actions")}
          dataIndex="actions"
          key="actions"
          render={(_value, record) => (
            <Space>
              <EditButton size="small" recordItemId={record.id} />
              <ShowButton size="small" recordItemId={record.id} />
            </Space>
          )}
        />
      </Table>
    </List>
  );
};
interfaces/index.d.ts
export interface ICategory {
  id: number;
  title: string;
}

export interface IPost {
  id: number;
  title: string;
  content: string;
  status: "published" | "draft" | "rejected";
  category: { id: number };
}
Language change action

Translation file​

All of Refine's components supports i18n, meaning that if you want to change their text, you can create your own translation files to override Refine's default texts.

Here is the list of all translation keys that you can override:

Show translation file
/locales/en/common.json
{
  "pages": {
    "login": {
      "title": "Sign in to your account",
      "signin": "Sign in",
      "signup": "Sign up",
      "divider": "or",
      "fields": {
        "email": "Email",
        "password": "Password"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required",
        "requiredPassword": "Password is required"
      },
      "buttons": {
        "submit": "Login",
        "forgotPassword": "Forgot password?",
        "noAccount": "Don’t have an account?",
        "rememberMe": "Remember me"
      }
    },
    "forgotPassword": {
      "title": "Forgot your password?",
      "fields": {
        "email": "Email"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required"
      },
      "buttons": {
        "submit": "Send reset instructions"
      }
    },
    "register": {
      "title": "Sign up for your account",
      "fields": {
        "email": "Email",
        "password": "Password"
      },
      "errors": {
        "validEmail": "Invalid email address",
        "requiredEmail": "Email is required",
        "requiredPassword": "Password is required"
      },
      "buttons": {
        "submit": "Register",
        "haveAccount": "Have an account?"
      }
    },
    "updatePassword": {
      "title": "Update password",
      "fields": {
        "password": "New Password",
        "confirmPassword": "Confirm new password"
      },
      "errors": {
        "confirmPasswordNotMatch": "Passwords do not match",
        "requiredPassword": "Password required",
        "requiredConfirmPassword": "Confirm password is required"
      },
      "buttons": {
        "submit": "Update"
      }
    },
    "error": {
      "info": "You may have forgotten to add the {{action}} component to {{resource}} resource.",
      "404": "Sorry, the page you visited does not exist.",
      "resource404": "Are you sure you have created the {{resource}} resource.",
      "backHome": "Back Home"
    }
  },
  "actions": {
    "list": "List",
    "create": "Create",
    "edit": "Edit",
    "show": "Show"
  },
  "buttons": {
    "create": "Create",
    "save": "Save",
    "logout": "Logout",
    "delete": "Delete",
    "edit": "Edit",
    "cancel": "Cancel",
    "confirm": "Are you sure?",
    "filter": "Filter",
    "clear": "Clear",
    "refresh": "Refresh",
    "show": "Show",
    "undo": "Undo",
    "import": "Import",
    "clone": "Clone",
    "notAccessTitle": "You don't have permission to access"
  },
  "warnWhenUnsavedChanges": "Are you sure you want to leave? You have unsaved changes.",
  "notifications": {
    "success": "Successful",
    "error": "Error (status code: {{statusCode}})",
    "undoable": "You have {{seconds}} seconds to undo",
    "createSuccess": "Successfully created {{resource}}",
    "createError": "There was an error creating {{resource}} (status code: {{statusCode}})",
    "deleteSuccess": "Successfully deleted {{resource}}",
    "deleteError": "Error when deleting {{resource}} (status code: {{statusCode}})",
    "editSuccess": "Successfully edited {{resource}}",
    "editError": "Error when editing {{resource}} (status code: {{statusCode}})",
    "importProgress": "Importing: {{processed}}/{{total}}"
  },
  "loading": "Loading",
  "tags": {
    "clone": "Clone"
  },
  "dashboard": {
    "title": "Dashboard"
  },
  "posts": {
    "posts": "Posts",
    "fields": {
      "id": "Id",
      "title": "Title",
      "category": "Category",
      "status": {
        "title": "Status",
        "published": "Published",
        "draft": "Draft",
        "rejected": "Rejected"
      },
      "content": "Content",
      "createdAt": "Created At"
    },
    "titles": {
      "create": "Create Post",
      "edit": "Edit Post",
      "list": "Posts",
      "show": "Show Post"
    }
  },
  "table": {
    "actions": "Actions"
  },
  "documentTitle": {
    "default": "refine",
    "suffix": " | Refine",
    "post": {
      "list": "Posts | Refine",
      "show": "#{{id}} Show Post | Refine",
      "edit": "#{{id}} Edit Post | Refine",
      "create": "Create new Post | Refine",
      "clone": "#{{id}} Clone Post | Refine"
    }
  },
  "autoSave": {
    "success": "saved",
    "error": "auto save failure",
    "loading": "saving...",
    "idle": "waiting for changes"
  }
}
Previous
Import - Export
Next
Usage with Existing Projects