feat: list formatter example

cwtuan · cwtuan · commit 3622ca220839 · 2026-07-13T13:48:07.000+08:00
diff --git a/packages/react-intl-universal/examples/nextjs-example/components/locale-formatting.tsx b/packages/react-intl-universal/examples/nextjs-example/components/locale-formatting.tsx
@@ -0,0 +1,44 @@
+import React from 'react';
+import intl from 'core/intl';
+import ExampleBlock from 'components/example-block';
+import { renderCode } from 'components/format-doc-links';
+
+const LocaleFormattingComponent: React.FC = () => {
+  const formatListCode = `<div>
+  {intl.formatList([
+    <strong key="react">React</strong>,
+    <strong key="typescript">TypeScript</strong>,
+    <strong key="nextjs">Next.js</strong>,
+  ], { type: 'conjunction', style: 'long' })}
+</div>`;
+
+  const formatParenthesesCode = `<div>
+  {intl.formatParentheses(
+    <strong key="beta">{intl.get('EXAMPLE_STATUS_BETA').d('Beta')}</strong>
+  )}
+</div>`;
+
+  const getColonCode = `<div>
+  {intl.get('EXAMPLE_STATUS').d('Status')}
+  {intl.getColon()}
+  <strong>{intl.get('EXAMPLE_STATUS_ACTIVE').d('Active')}</strong>
+</div>`;
+
+  return (
+    <div>
+      <div className="title">
+        {intl.get('EXAMPLE_TITLE_LOCALE_HELPERS').d('Locale-aware lists and punctuation')}
+      </div>
+      <p className="section-note">
+        {intl.get('EXAMPLE_NOTE_LOCALE_HELPERS', {
+          code: renderCode,
+        }).d('Use <code>intl.formatList</code> to join React nodes and use <code>intl.formatParentheses</code> or <code>intl.getColon</code> for punctuation that matches the active locale.')}
+      </p>
+      <ExampleBlock code={formatListCode} />
+      <ExampleBlock code={formatParenthesesCode} />
+      <ExampleBlock code={getColonCode} />
+    </div>
+  );
+};
+
+export default LocaleFormattingComponent;
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/de-DE.json b/packages/react-intl-universal/examples/nextjs-example/locales/de-DE.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "Sprachabhängige Listen und Satzzeichen",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "Verwenden Sie <code>intl.formatList</code> zum Verbinden von React-Knoten und <code>intl.formatParentheses</code> oder <code>intl.getColon</code> für Satzzeichen, die zur aktiven Sprache passen.",
+  "EXAMPLE_STATUS_BETA": "Beta",
+  "EXAMPLE_STATUS": "Status",
+  "EXAMPLE_STATUS_ACTIVE": "Aktiv",
   "EXAMPLE_NOTE_PLAIN": "Schreiben Sie ICU variables in die <code>.d()</code> default message und übergeben Sie die Werte über den zweiten Parameter von <code>intl.get</code>. So bleiben Code, default message und Extraktion konsistent. Details finden Sie in der <formatjs>FormatJS ICU syntax</formatjs>.",
   "EXAMPLE_NOTE_PLURAL": "Plural messages verwenden ICU <code>plural</code> rules. Der <code>#</code> placeholder wird mit der aktiven locale formatiert, deshalb erhalten große Zahlen automatisch passende Trennzeichen. Mehr dazu im <icu>ICU MessageFormat guide</icu>.",
   "EXAMPLE_NOTE_DATE_TIME": "Formatieren Sie JavaScript Date-Werte mit intl.formatDate, intl.formatTime oder intl.formatDateTime und übergeben Sie das Ergebnis dann an intl.get. Diese Helper verwenden stabile Standardformate: YYYY-MM-DD, HH:mm:ss und YYYY-MM-DD HH:mm:ss. Die locale message enthält nur einfache Platzhalter wie '{start}'.",
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/en-US.json b/packages/react-intl-universal/examples/nextjs-example/locales/en-US.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "Locale-aware lists and punctuation",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "Use <code>intl.formatList</code> to join React nodes and use <code>intl.formatParentheses</code> or <code>intl.getColon</code> for punctuation that matches the active locale.",
+  "EXAMPLE_STATUS_BETA": "Beta",
+  "EXAMPLE_STATUS": "Status",
+  "EXAMPLE_STATUS_ACTIVE": "Active",
   "EXAMPLE_NOTE_PLAIN": "Use ICU variables with the values passed to <code>intl.get</code>. Keep <code>.d()</code> as the default message and source text for extraction. See <formatjs>FormatJS ICU syntax</formatjs> for details.",
   "EXAMPLE_NOTE_PLURAL": "Plural messages use ICU <code>plural</code> rules. The <code>#</code> placeholder is formatted with the active locale, so large numbers get locale-aware separators. Learn more in the <icu>ICU MessageFormat guide</icu>.",
   "EXAMPLE_NOTE_DATE_TIME": "Format JavaScript Date values with intl.formatDate, intl.formatTime, or intl.formatDateTime, then pass the formatted value into intl.get. The helpers use stable defaults: YYYY-MM-DD, HH:mm:ss, and YYYY-MM-DD HH:mm:ss. Locale messages keep plain placeholders such as '{start}'.",
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/es-ES.json b/packages/react-intl-universal/examples/nextjs-example/locales/es-ES.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "Listas y puntuación adaptadas al idioma",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "Usa <code>intl.formatList</code> para unir nodos de React y <code>intl.formatParentheses</code> o <code>intl.getColon</code> para generar signos de puntuación adecuados para el idioma activo.",
+  "EXAMPLE_STATUS_BETA": "Beta",
+  "EXAMPLE_STATUS": "Estado",
+  "EXAMPLE_STATUS_ACTIVE": "Activo",
   "EXAMPLE_NOTE_PLAIN": "Usa ICU variables con los valores pasados a <code>intl.get</code>. Mantén <code>.d()</code> como default message y source text para la extracción. Consulta <formatjs>FormatJS ICU syntax</formatjs> para más detalles.",
   "EXAMPLE_NOTE_PLURAL": "Los plural messages usan las reglas ICU <code>plural</code>. El placeholder <code>#</code> se formatea con el locale activo, así que los números grandes usan separadores adecuados al idioma. Más detalles en la <icu>ICU MessageFormat guide</icu>.",
   "EXAMPLE_NOTE_DATE_TIME": "Formatea valores JavaScript Date con intl.formatDate, intl.formatTime o intl.formatDateTime, y luego pasa el resultado a intl.get. Estos helpers usan defaults estables: YYYY-MM-DD, HH:mm:ss y YYYY-MM-DD HH:mm:ss. Los locale messages conservan placeholders simples como '{start}'.",
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/fr-FR.json b/packages/react-intl-universal/examples/nextjs-example/locales/fr-FR.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "Listes et ponctuation adaptées à la langue",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "Utilisez <code>intl.formatList</code> pour joindre des nœuds React, et <code>intl.formatParentheses</code> ou <code>intl.getColon</code> pour obtenir une ponctuation adaptée à la langue active.",
+  "EXAMPLE_STATUS_BETA": "Bêta",
+  "EXAMPLE_STATUS": "État",
+  "EXAMPLE_STATUS_ACTIVE": "Actif",
   "EXAMPLE_NOTE_PLAIN": "Utilisez des ICU variables avec les valeurs passées à <code>intl.get</code>. Gardez <code>.d()</code> comme message par défaut et comme texte source pour l'extraction. Voir <formatjs>FormatJS ICU syntax</formatjs> pour les détails.",
   "EXAMPLE_NOTE_PLURAL": "Les plural messages utilisent les règles ICU <code>plural</code>. Le placeholder <code>#</code> est formaté selon la locale active, donc les grands nombres reçoivent les séparateurs adaptés. Voir le <icu>ICU MessageFormat guide</icu>.",
   "EXAMPLE_NOTE_DATE_TIME": "Formatez les valeurs JavaScript Date avec intl.formatDate, intl.formatTime ou intl.formatDateTime, puis passez le résultat à intl.get. Ces helpers utilisent des formats stables par défaut : YYYY-MM-DD, HH:mm:ss et YYYY-MM-DD HH:mm:ss. Le locale message garde de simples placeholders comme '{start}'.",
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/ja-JP.json b/packages/react-intl-universal/examples/nextjs-example/locales/ja-JP.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages（複数形）",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting（日付と時刻）",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting（数値の整形）",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "ロケール対応のリストと句読点",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "<code>intl.formatList</code> で React ノードを連結し、<code>intl.formatParentheses</code> または <code>intl.getColon</code> で現在のロケールに合った句読点を生成します。",
+  "EXAMPLE_STATUS_BETA": "ベータ",
+  "EXAMPLE_STATUS": "状態",
+  "EXAMPLE_STATUS_ACTIVE": "有効",
   "EXAMPLE_NOTE_PLAIN": "ICU variables を <code>.d()</code> の default message に書き、値は <code>intl.get</code> の第 2 引数で渡します。これによりコード、default message、抽出ツールの前提がそろいます。詳しくは <formatjs>FormatJS ICU syntax</formatjs> を参照してください。",
   "EXAMPLE_NOTE_PLURAL": "Plural messages は ICU の <code>plural</code> rules を使います。<code>#</code> は現在の locale に合わせて数値をフォーマットするため、大きな数値の区切りも locale に従います。詳しくは <icu>ICU MessageFormat guide</icu> を参照してください。",
   "EXAMPLE_NOTE_DATE_TIME": "JavaScript Date は、先に intl.formatDate、intl.formatTime、intl.formatDateTime で整形してから intl.get に渡します。これらの helper は YYYY-MM-DD、HH:mm:ss、YYYY-MM-DD HH:mm:ss の安定した既定形式を使います。locale message には '{start}' のような通常の placeholder だけを残します。",
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/ko-KR.json b/packages/react-intl-universal/examples/nextjs-example/locales/ko-KR.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "로캘별 목록 및 문장 부호",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "<code>intl.formatList</code>로 React 노드를 연결하고 <code>intl.formatParentheses</code> 또는 <code>intl.getColon</code>으로 현재 로캘에 맞는 문장 부호를 생성하세요.",
+  "EXAMPLE_STATUS_BETA": "베타",
+  "EXAMPLE_STATUS": "상태",
+  "EXAMPLE_STATUS_ACTIVE": "활성",
   "EXAMPLE_NOTE_PLAIN": "ICU variables는 <code>.d()</code> default message에 쓰고, 값은 <code>intl.get</code>의 두 번째 인자로 전달하세요. 이렇게 하면 코드, default message, extract 결과가 같은 기준을 공유합니다. 자세한 문법은 <formatjs>FormatJS ICU syntax</formatjs>를 참고하세요.",
   "EXAMPLE_NOTE_PLURAL": "Plural messages는 ICU <code>plural</code> rules를 사용합니다. <code>#</code> placeholder는 현재 locale에 맞게 숫자를 포맷하므로 큰 숫자도 locale에 맞는 구분 기호를 사용합니다. 자세한 내용은 <icu>ICU MessageFormat guide</icu>를 참고하세요.",
   "EXAMPLE_NOTE_DATE_TIME": "JavaScript Date 값은 intl.formatDate, intl.formatTime, intl.formatDateTime으로 먼저 포맷한 뒤 intl.get에 전달하세요. 이 helper들은 YYYY-MM-DD, HH:mm:ss, YYYY-MM-DD HH:mm:ss처럼 안정적인 기본 형식을 사용합니다. locale message에는 '{start}' 같은 일반 placeholder만 남깁니다.",
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/zh-CN.json b/packages/react-intl-universal/examples/nextjs-example/locales/zh-CN.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages（复数场景）",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting（日期时间）",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting（数字格式化）",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "本地化列表与标点",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "使用 <code>intl.formatList</code> 连接 React 节点，并使用 <code>intl.formatParentheses</code> 或 <code>intl.getColon</code> 生成符合当前语言习惯的标点。",
+  "EXAMPLE_STATUS_BETA": "测试版",
+  "EXAMPLE_STATUS": "状态",
+  "EXAMPLE_STATUS_ACTIVE": "启用",
   "EXAMPLE_NOTE_PLAIN": "把 ICU variables 写在 <code>.d()</code> 默认文案里，再通过 <code>intl.get</code> 第二个参数传值。这样代码、默认文案和抽取工具会保持一致。更多语法见 <formatjs>FormatJS ICU syntax</formatjs>。",
   "EXAMPLE_NOTE_PLURAL": "Plural messages 使用 ICU <code>plural</code> rules。<code>#</code> 会按当前 locale 格式化数字，所以大数字会自动带上对应语言环境的分隔符。详细规则见 <icu>ICU MessageFormat guide</icu>。",
   "EXAMPLE_NOTE_DATE_TIME": "先用 intl.formatDate、intl.formatTime 或 intl.formatDateTime 格式化 JavaScript Date，再把结果传给 intl.get。这三个 helper 使用稳定默认格式：YYYY-MM-DD、HH:mm:ss、YYYY-MM-DD HH:mm:ss。locale message 只保留 '{start}' 这类普通占位符。",
diff --git a/packages/react-intl-universal/examples/nextjs-example/locales/zh-TW.json b/packages/react-intl-universal/examples/nextjs-example/locales/zh-TW.json
@@ -16,6 +16,11 @@
   "EXAMPLE_TITLE_PLURAL": "Plural messages（複數情境）",
   "EXAMPLE_TITLE_DATE_TIME": "Date and time formatting（日期時間）",
   "EXAMPLE_TITLE_NUMBER_CURRENCY": "Number formatting（數字格式化）",
+  "EXAMPLE_TITLE_LOCALE_HELPERS": "在地化清單與標點",
+  "EXAMPLE_NOTE_LOCALE_HELPERS": "使用 <code>intl.formatList</code> 串接 React 節點，並使用 <code>intl.formatParentheses</code> 或 <code>intl.getColon</code> 產生符合目前語系習慣的標點。",
+  "EXAMPLE_STATUS_BETA": "測試版",
+  "EXAMPLE_STATUS": "狀態",
+  "EXAMPLE_STATUS_ACTIVE": "啟用",
   "EXAMPLE_NOTE_PLAIN": "把 ICU variables 寫在 <code>.d()</code> 預設文案裡，再透過 <code>intl.get</code> 第二個參數傳值。這樣程式碼、預設文案和抽取工具會保持一致。更多語法見 <formatjs>FormatJS ICU syntax</formatjs>。",
   "EXAMPLE_NOTE_PLURAL": "Plural messages 使用 ICU <code>plural</code> rules。<code>#</code> 會依照目前 locale 格式化數字，所以大數字會自動帶上對應語言環境的分隔符。詳細規則見 <icu>ICU MessageFormat guide</icu>。",
   "EXAMPLE_NOTE_DATE_TIME": "先用 intl.formatDate、intl.formatTime 或 intl.formatDateTime 格式化 JavaScript Date，再把結果傳給 intl.get。這三個 helper 使用穩定預設格式：YYYY-MM-DD、HH:mm:ss、YYYY-MM-DD HH:mm:ss。locale message 只保留 '{start}' 這類普通佔位符。",
diff --git a/packages/react-intl-universal/examples/nextjs-example/pages/index.tsx b/packages/react-intl-universal/examples/nextjs-example/pages/index.tsx
@@ -17,6 +17,7 @@ import SkillComponent from "components/skill";
 import ExtractComponent from "components/extract";
 import DateComponent from "components/date";
 import CurrencyComponent from "components/currency";
+import LocaleFormattingComponent from "components/locale-formatting";
 import MessageNotInComponent from "components/message-not-in-component";
 
 const LOCALES_LIST = [
@@ -191,6 +192,7 @@ const ReactIntlUniversalExample: React.FC<any> = (props) => {
               <PluralComponent />
               <DateComponent />
               <CurrencyComponent />
+              <LocaleFormattingComponent />
             </section>
 
             <section className="example-section" id="extract-usage">
