如何在 TanStack Start v1 中标记混合语言内容

问题

当页面包含多种语言的文本时，浏览器和辅助技术会假设所有内容都使用页面声明的语言。一台配置为英语的屏幕阅读器会尝试用英语发音规则来朗读法语短语、西班牙语书名或德语公司名称，从而为依赖音频的用户生成难以理解的输出。浏览器会应用错误的拼写检查规则，将正确拼写的外语单词标记为错误。排版引擎会错误处理不同语言之间的标点和间距规则。

这些问题为视力障碍用户制造了障碍，并使任何使用辅助技术的人更难理解内容。当外语术语频繁出现或内容包含较长的其他语言段落时，这些问题会更加严重。

解决方案

为每段外语文本标记一个 HTML lang 属性，标识其正确的语言，指示辅助技术临时切换发音引擎。在包围外语内容的元素上添加语言属性，以便对其进行不同的样式或处理。这种分离允许屏幕阅读器正确朗读每种语言，并使浏览器能够对每个片段应用适当的排版和拼写检查规则。

步骤

1. 创建一个用于标记外语文本的组件

将外语文本包裹在带有 lang 属性的元素中，使用惯用的文本元素而不是 span，因为某些屏幕阅读器会忽略 span 上的 lang 属性。

interface ForeignTextProps {
  lang: string;
  children: React.ReactNode;
}

export function ForeignText({ lang, children }: ForeignTextProps) {
  return <i lang={lang}>{children}</i>;
}

i 元素表示以另一种语气或语调呈现的文本，包括其他语言的术语，并确保屏幕阅读器尊重语言属性。

2. 使用组件标记内嵌的外语短语

将组件应用于内容中的外语单词或短语，并指定适当的语言代码。

import { ForeignText } from "~/components/ForeignText";

export default function ArticlePage() {
  return (
    <article>
      <p>
        The book <ForeignText lang="es">Cien años de soledad</ForeignText> is
        considered a masterpiece of magical realism.
      </p>
      <p>
        She said <ForeignText lang="fr">c'est la vie</ForeignText> and walked
        away.
      </p>
    </article>
  );
}

适当元素上的 lang 属性会指示辅助技术暂时切换语言，从而确保准确的发音。

3. 标记较长的外语段落

对于多句的外语内容，将 lang 属性直接应用于块级元素。

export default function QuotePage() {
  return (
    <article>
      <p>The original German text reads:</p>
      <blockquote lang="de">
        <p>Die Grenzen meiner Sprache bedeuten die Grenzen meiner Welt.</p>
      </blockquote>
      <p>
        This translates to: The limits of my language mean the limits of my
        world.
      </p>
    </article>
  );
}

lang 属性几乎可以与所有 HTML 元素一起使用，这使得通过将该属性添加到诸如 blockquote 等元素上，可以轻松地在页面内切换语言。

4. 查找内容的语言代码

使用 IANA 语言子标签注册表中的语言标签，您可以通过非官方的 Language Subtag Lookup 工具找到它们。

export default function MultilingualPage() {
  return (
    <div>
      <p>
        Common examples: <ForeignText lang="fr">bonjour</ForeignText> (French),
        <ForeignText lang="de">Gesundheit</ForeignText> (German),
        <ForeignText lang="ja">ありがとう</ForeignText> (Japanese),
        <ForeignText lang="ar">شكرا</ForeignText> (Arabic)
      </p>
    </div>
  );
}

对于任何语言，如果存在两字母代码，请使用它；如果没有其他代码可用，则仅使用三字母代码。