@k8ordo/i18n

文言

messageで文言を宣言し、コンポーネントから呼べるようにします。値を差し込む文言を作り、Server ComponentからClient Componentへ渡せるようになります。

このページの内容

文だけの文言

src/messages/nav.ts
import { message } from '@k8ordo/i18n';

export const home = message({ ja: 'ホーム', en: 'Home' });

export const search = message({ ja: '検索', en: 'Search' });

ロケールをキーに、そのロケールの文を書きます。messageは引数を取らない関数を返し、呼ぶたびにその時点のロケールを読みます。

ts
export const save = message({ ja: '保存' });
enが無いので型エラーになる

ロケールの型がRegisterに登録されていれば、ロケールが1つでも欠けた文言は型エラーになります。一覧に無いロケールを書いた場合も同じです。

どこもロケールを指定していないときは、既定のロケールの文を返します。そうなる場面の一覧はロケールにあります。

値を差し込む文言

src/messages/cart.ts
import { message } from '@k8ordo/i18n';

export const added = message({
  ja: (name: string) => `${name}をカートに入れました`,
  en: (name) => `Added ${name} to your cart`,
});

値を差し込む文言は、すべてのロケールを同じ引数の関数で書きます。値を使わないロケールも関数にして、(_count) => 'Items'のように引数を宣言します。引数を省いた関数は、置いたロケールによって型エラーになったり、検査をすり抜けたりします。1つの文言の中で、文と関数は混ぜられません。

差し込みはテンプレートリテラルで書きます。引数の型はどれか1つのロケールに書けば、ほかのロケールも同じ型で検査されます。呼ぶ側が渡す値も、同じ型で検査されます。

src/lib/cart-notice.ts
import { added } from '../messages/cart';

added('Lamp');
added(3);
`number`は渡せないので型エラーになる

複数形や日付、数値は、関数の中でIntlを使って書きます。書き方は日付と数値の書式にあります。

警告

落とし穴

どのロケールにも型を書かないと、引数はunknownになり、どんな値でも通ります。少なくとも1つのロケールに書くか、message<[name: string]>({ … })のように型引数で渡します。

置き場所

src/components/header.tsx
import { home, search } from '../messages/nav';

export function Header() {
  return (
    <nav>
      <a href="/">{home()}</a>
      <a href="/search">{search()}</a>
    </nav>
  );
}

文言はどのファイルに置いてもかまいません。領域ごとに1つのファイルをsrc/messages/に置き、使う側は要る文言だけを名前でimportします。別のファイルの同じ名前は、import { title as cartTitle }のように付け替えます。

1つのコンポーネントだけが使う文言は、そのコンポーネントのモジュールの中に書けます。関係の深い文言をオブジェクトにまとめることもできます。ただし、使わない文言もオブジェクトごとバンドルに残ります。

呼ぶ場所

src/lib/menu.ts
import type { Message } from '@k8ordo/i18n';

import { home, search } from '../messages/nav';

export const MENU = [home(), search()];
export const MENU: readonly Message[] = [home, search];

モジュールのトップレベルで文言を呼んで文字列にすると、その時点のロケールで固定されます。

サーバーでは、モジュールはたいていロケールが設定される前に読み込まれるので、既定のロケールの文字列になります。ブラウザでは、モジュールを読み込んだときのURLのロケールで固定され、言語を切り替えても変わりません。

Messageのまま持っておき、描画するコンポーネントで呼びます。

Message型のprops

src/components/nav-list.tsx
import type { Message } from '@k8ordo/i18n';

type NavItem = { href: string; label: Message };

export function NavList({ items }: { items: readonly NavItem[] }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.href}>
          <a href={item.href}>{item.label()}</a>
        </li>
      ))}
    </ul>
  );
}

文言を受け取るコンポーネントは、propsをMessage型にして、描画するときに呼びます。

値を差し込む文言は、Message<[name: string]>のように引数の組を型引数に書きます。文字列にするのは描画するコンポーネントだけなので、データを組み立てる側はロケールを知らずに済みます。

受け渡し

文言は関数なので、Server ComponentからClient Componentへpropsとして渡せません。Reactは関数をシリアライズできないので、Functions cannot be passed directly to Client Componentsというエラーになります。

文字列のprops

src/components/share-section.tsx
import { copied, copyLink } from '../messages/share';
import { CopyLink } from './copy-link';

export function ShareSection() {
  return <CopyLink copied={copied()} label={copyLink()} />;
}
src/components/copy-link.tsx
'use client';

import { useState } from 'react';

type Props = { copied: string; label: string };

export function CopyLink({ copied, label }: Props) {
  const [done, setDone] = useState(false);

  return (
    <button
      onClick={() => {
        void navigator.clipboard.writeText(location.href).then(() => {
          setDone(true);
        });
      }}
      type="button"
    >
      {done ? copied : label}
    </button>
  );
}

Server ComponentのShareSectionが文言を呼び、今のロケールの文字列を渡します。文言そのものは、ブラウザのバンドルに入りません。

情報

メモ

ビルドしたブラウザ向けのJavaScriptを検索すると、Server Componentだけが描画する文が無いことを確かめられます。

直接のimport

src/components/copy-link.tsx
'use client';

import { useState } from 'react';

import { copied, copyLink } from '../messages/share';

export function CopyLink() {
  const [done, setDone] = useState(false);

  return (
    <button
      onClick={() => {
        void navigator.clipboard.writeText(location.href).then(() => {
          setDone(true);
        });
      }}
      type="button"
    >
      {done ? copied() : copyLink()}
    </button>
  );
}

Client Componentが自分で文言をimportして呼ぶこともできます。その文言は、すべてのロケールの文を持ったままブラウザのバンドルに入ります。

入力に応じて変わる文や、ボタンを押したあとに出す文のように、ブラウザで決まる文に向いています。

どの文言がブラウザのバンドルに入るかは仕組みにあります。

ディレクティブ無し

ディレクティブの無いコンポーネントは、描画したコンポーネントと同じ側で実行されます。Server Componentからならサーバー、Client Componentからならブラウザです。どちらの場合もpropsはシリアライズされないので、Message型のpropsを受け取れます。

ページのタイトルのように、propsと文言を読むだけのコンポーネントには'use client'を付けません。

k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。