TanStack Start v1에서 혼합 언어 콘텐츠 표시하기

문제

페이지에 여러 언어의 텍스트가 포함되어 있으면, 브라우저와 보조 기술은 모든 콘텐츠가 페이지에 선언된 언어로 작성되었다고 가정합니다. 영어로 설정된 화면 읽기 도구는 프랑스어 문구, 스페인어 책 제목, 독일어 회사 이름 등을 영어 발음으로 읽으려 하여, 화면 읽기에 의존하는 사용자는 이를 제대로 이해할 수 없습니다. 브라우저는 잘못된 맞춤법 검사 규칙을 적용해 올바른 외국어 단어도 오류로 표시하고, 타이포그래피 엔진은 언어마다 다른 문장 부호와 공백 규칙을 잘못 처리합니다.

이러한 문제는 시각장애가 있는 사용자에게 장벽이 될 뿐만 아니라, 보조 기술을 사용하는 모든 사람이 내용을 이해하기 더 어렵게 만듭니다. 외국어 용어가 자주 나오거나, 다른 언어로 된 긴 단락이 포함될 때 문제는 더욱 심화됩니다.

해결 방법

각 외국어 텍스트 조각마다 올바른 언어를 식별하는 HTML lang 속성을 추가하여, 보조 기술이 일시적으로 발음 엔진을 전환하도록 안내하세요. 외국어 콘텐츠를 감싸는 요소에 언어 속성을 추가해 스타일이나 처리를 다르게 할 수도 있습니다. 이렇게 분리하면 화면 읽기 도구가 각 언어를 올바로 읽어주고, 브라우저도 각 부분에 맞는 타이포그래피와 맞춤법 검사를 적용할 수 있습니다.

단계

1. 외국어 표기를 위한 컴포넌트 만들기

외국어 텍스트는 lang 속성이 있는 요소로 감싸세요. 일부 화면 읽기 도구가 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 Registry의 언어 태그를 사용하세요. 비공식 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>
  );
}

사용할 언어에 2글자 코드가 있다면 그것을, 없다면 3글자 코드를 사용하세요.