GatsbyJS에서 다국어(i18n) 지원 구현하기

GatsbyJS에서 다국어(i18n) 지원 구현하기

GatsbyJS로 글로벌 웹사이트를 운영하려면 다국어(i18n) 지원이 필수적입니다.
이번 글에서는 Gatsby에서 다국어를 지원하는 방법을 단계별로 설명하겠습니다. 🚀

---

1. Gatsby 다국어(i18n) 적용 방식

Gatsby에서 다국어를 적용하는 방법은 여러 가지가 있습니다.
✅ 다국어 적용 방식 비교

방법 설명 장점 단점

파일 기반 라우팅	en/index.js, ko/index.js처럼 별도 페이지 생성	간단한 구현	유지보수 어려움
URL 구조 활용	/en/, /ko/ 등 언어별 경로 사용	SEO 친화적	URL 구조 변경 필요
gatsby-plugin-intl 활용	자동 다국어 처리 지원	유지보수 용이	추가 패키지 필요
react-intl 활용	JSON 기반 다국어 지원	번역 관리 용이	설정이 필요

🚀 이번 글에서는 gatsby-plugin-react-i18next를 사용하여 다국어 기능을 구현합니다.

---

2. gatsby-plugin-react-i18next 설치 및 설정

✅ 플러그인 설치

npm install gatsby-plugin-react-i18next react-i18next i18next

✅ 언어 JSON 파일 생성 (src/locales/ko.json, src/locales/en.json)

반응형

📌 src/locales/ko.json (한국어)

{
  "hello": "안녕하세요!",
  "welcome": "Gatsby 다국어 지원 예제입니다."
}

📌 src/locales/en.json (영어)

{
  "hello": "Hello!",
  "welcome": "This is a Gatsby i18n example."
}

✅ gatsby-config.js 설정

module.exports = {
  siteMetadata: {
    siteUrl: "https://example.com",
  },
  plugins: [
    {
      resolve: "gatsby-plugin-react-i18next",
      options: {
        languages: ["en", "ko"],
        defaultLanguage: "en",
        siteUrl: "https://example.com",
        i18nextOptions: {
          interpolation: { escapeValue: false },
        },
      },
    },
  ],
};

---

3. 다국어 지원을 위한 레이아웃 설정

✅ 다국어 선택 버튼 추가 (src/components/LanguageSwitcher.js)

import React from "react";
import { useI18next } from "gatsby-plugin-react-i18next";

const LanguageSwitcher = () => {
  const { languages, language, changeLanguage } = useI18next();

  return (
    <div>
      {languages.map(lang => (
        <button
          key={lang}
          onClick={() => changeLanguage(lang)}
          disabled={lang === language}
        >
          {lang.toUpperCase()}
        </button>
      ))}
    </div>
  );
};

export default LanguageSwitcher;

🚀 이제 사용자는 버튼을 클릭하여 언어를 변경할 수 있습니다.

---

4. 다국어 적용된 페이지 만들기

✅ src/pages/index.js에서 다국어 텍스트 적용

import React from "react";
import { useTranslation } from "gatsby-plugin-react-i18next";
import LanguageSwitcher from "../components/LanguageSwitcher";

const HomePage = () => {
  const { t } = useTranslation();

  return (
    <main>
      <h1>{t("hello")}</h1>
      <p>{t("welcome")}</p>
      <LanguageSwitcher />
    </main>
  );
};

export default HomePage;

🚀 이제 다국어가 적용된 웹사이트가 완성되었습니다!

---

5. 다국어 SEO 최적화 (gatsby-plugin-sitemap 활용)

검색 엔진이 다국어 페이지를 올바르게 인식할 수 있도록 sitemap.xml을 설정해야 합니다.

✅ gatsby-plugin-sitemap 설치

npm install gatsby-plugin-sitemap

✅ gatsby-config.js 설정 추가

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-sitemap",
      options: {
        query: `
          {
            site {
              siteMetadata {
                siteUrl
              }
            }
            allSitePage {
              nodes {
                path
              }
            }
          }
        `,
        resolvePages: ({ allSitePage }) => allSitePage.nodes,
        serialize: ({ path }) => ({ url: path }),
      },
    },
  ],
};

🚀 이제 다국어 페이지가 검색 엔진에 최적화됩니다.

---

6. 다국어 페이지 경로 설정

다국어 URL을 다음과 같이 설정할 수 있습니다.

언어 URL 구조

🇺🇸 영어	/en/
🇰🇷 한국어	/ko/

✅ SEO에 최적화된 다국어 URL을 설정하려면 Gatsby의 createPages를 활용해야 합니다.

✅ gatsby-node.js에서 다국어 페이지 자동 생성

exports.createPages = async ({ actions, graphql }) => {
  const { createPage } = actions;
  const languages = ["en", "ko"];

  languages.forEach(lang => {
    createPage({
      path: `/${lang}/`,
      component: require.resolve("./src/templates/home.js"),
      context: { lang },
    });
  });
};

🚀 이제 /en/과 /ko/ 경로에 다국어 페이지가 자동 생성됩니다.

---

7. 결론

이번 글에서는 Gatsby에서 다국어(i18n) 지원을 추가하는 방법을 배웠습니다.
✔ gatsby-plugin-react-i18next를 활용한 다국어 지원
✔ JSON 파일을 활용하여 번역 텍스트 관리
✔ 다국어 버튼을 추가하여 동적 변경 기능 구현
✔ SEO 최적화를 위해 gatsby-plugin-sitemap 및 createPages 활용

🚀 다음 글에서는 GatsbyJS에서 동적 콘텐츠를 생성하는 방법을 다루겠습니다!