웹사이트 국제화
Next.js 웹사이트에 다국어 지원을 추가하고 SEO 모범 사례를 적용하는 완전한 워크플로우입니다.
이 스킬을 사용해야 할 때
- 기존 웹사이트에 새 언어 버전 추가
- 새 웹사이트에 i18n(국제화) 설정
- 여러 언어에 대한 SEO 구성
- 사용자가 "언어 추가", "번역", "현지화", "hreflang", "다국어"를 언급할 때
지원 언어
일반적인 타겟 시장:
- 🇺🇸 영어 (en) - 글로벌 시장
- 🇯🇵 일본어 (ja) - 아시아 시장
- 🇨🇳 중국어 (zh) - 중국 시장
확장 지원 가능:
- 한국어 (ko), 포르투갈어 (pt), 스페인어 (es), 프랑스어 (fr), 독일어 (de)
- 아랍어 (ar), 베트남어 (vi), 힌디어 (hi), 인도네시아어 (id), 태국어 (th)
- 중국어 번체 (zh-hk), 이탈리아어 (it), 러시아어 (ru)
국제화 워크플로우
이 체크리스트를 복사하여 진행 상황을 추적하세요:
i18n 진행 상황:
- [ ] 1단계: 기본 언어 파일 준비
- [ ] 2단계: 새 언어 파일 추가
- [ ] 3단계: 구성 파일 업데이트
- [ ] 4단계: 번역 추가
- [ ] 5단계: SEO 요소 구성
- [ ] 6단계: 검증 및 테스트
1단계: 기본 언어 파일 준비
영어 (en.json) 파일이 템플릿으로 존재하는지 확인하세요:
필수 디렉토리:
i18n/messages/en.json- 주요 번역i18n/pages/landing/en.json- 랜딩 페이지 번역
구조 확인:
# 기본 파일 존재 여부 확인
ls i18n/messages/en.json
ls i18n/pages/landing/en.json
파일이 없으면 웹사이트에 필요한 완전한 번역 키를 포함하여 생성하세요.
2단계: 새 언어 파일 추가
언어 추가 스크립트를 실행하세요:
node scripts/i18n-add-languages.mjs
이 스크립트가 수행하는 작업:
en.json을 모든 대상 언어 파일로 복사i18n/locale.ts를 새 로케일로 업데이트i18n/request.ts를 언어 매핑으로 업데이트public/sitemap.xml을 새 언어 URL로 업데이트
스크립트 구성 (i18n-add-languages.mjs 파일 내):
languages배열 - 추가할 언어 목록languageNames객체 - 언어 표시 이름targetDirs배열 - 번역 파일을 포함하는 디렉토리
자세한 단계별 가이드는 WORKFLOW.md를 참조하세요.
3단계: 구성 업데이트 확인
i18n/locale.ts 확인:
export const locales = ["en", "ja", "zh", "ko", ...];
export const localeNames: any = {
en: "English",
ja: "日本語",
zh: "中文",
ko: "한국어",
...
};
i18n/request.ts 확인:
- 언어 코드 매핑이 구성되었는지 확인
zh-CN→zh,zh-HK→zh-hk매핑이 존재하는지 확인
public/sitemap.xml 확인:
- 모든 언어 버전이 나열되었는지 확인
- 각 URL에
hreflang태그가 있는지 확인
4단계: 번역 추가
옵션 A: AI 번역 사용 (빠르지만 검토 필요):
# 구조화된 데이터 및 가격 번역 추가
node scripts/i18n-add-schema.js
스크립트의 translations 객체에서 번역을 구성하세요.
옵션 B: 수동 번역 (품질 권장):
각 언어 파일을 적절한 번역으로 편집하세요:
# 언어 파일 열기
code i18n/messages/ja.json
번역 모범 사례:
- 가능하면 원어민을 활용하세요.
- 대상 언어로 SEO 키워드를 유지하세요.
- 단순히 번역하지 말고 콘텐츠를 현지 문화에 맞게 조정하세요.
- 서식(자리 표시자, 변수)의 일관성을 유지하세요.
언어 코드 참조는 reference/locale-codes.md를 참조하세요.
5단계: SEO 요소 구성
hreflang 태그 - 사이트맵을 통해 자동으로 처리되지만 확인하세요:
전체 가이드는 reference/hreflang-guide.md를 참조하세요.
지역화된 메타 태그 - 각 언어 파일에서 번역하세요:
{
"metadata": {
"title": "귀하의 사이트 제목",
"description": "귀하의 SEO 설명"
}
}
URL 구조 - 올바른 형식인지 확인하세요:
- 영어:
https://example.com/또는https://example.com/en/ - 일본어:
https://example.com/ja/ - 중국어:
https://example.com/zh/
6단계: 검증 및 테스트
프로젝트 빌드:
npm run build
중요: 계속 진행하기 전에 모든 오류를 수정하세요.
수동 테스트:
-
언어 전환기:
- 각 언어 버전을 방문하세요.
- 언어 전환기에 모든 언어가 표시되는지 확인하세요.
- 각 언어 링크를 클릭하고 올바른 페이지가 로드되는지 확인하세요.
-
콘텐츠 표시:
- 모든 페이지가 각 언어로 올바르게 렌더링되는지 확인하세요.
- 번역되지 않은 텍스트가 없는지 확인하세요(비영어 페이지에서 영어 텍스트 확인).
- 특수 문자가 올바르게 표시되는지 테스트하세요(일본어, 중국어, 아랍어).
-
SEO 요소:
<html lang="...">속성이 페이지 언어와 일치하는지 검사하세요.<link rel="alternate" hreflang="...">태그가 있는지 확인하세요.- 메타 태그가 올바른 언어로 되어 있는지 확인하세요.
자동화된 검증:
# 사이트맵 확인
curl https://your-site.com/sitemap.xml | grep hreflang
# hreflang 검증 (온라인 도구 사용)
# Google Search Console > Internationalization > hreflang
SEO 체크리스트 - reference/seo-checklist.md를 참조하세요.
검증 실패 시:
- 오류 메시지를 주의 깊게 검토하세요.
- 구성 파일에 오타가 있는지 확인하세요.
- 언어 코드가 올바른지 확인하세요.
- 3단계로 돌아가 문제를 수정하세요.
모든 검증이 통과된 경우에만 계속 진행하세요.
중요 참고 사항
언어 코드 표준
선택적 지역 변형과 함께 ISO 639-1(두 글자 코드)를 사용하세요:
en- 영어ja- 일본어zh- 중국어 간체zh-hk- 중국어 번체 (홍콩)pt- 포르투갈어pt-br- 브라질 포르투갈어
전체 목록은 reference/locale-codes.md를 참조하세요.
SEO 영향
올바른 i18n은 SEO를 개선합니다:
- 사용자의 모국어로 타겟팅
- 중복 콘텐츠 패널티 방지
- 검색 엔진이 올바른 언어 버전을 제공하도록 지원
피해야 할 일반적인 SEO 실수:
- ❌ IP 기반 자동 리디렉션 (검색 엔진이 모든 버전을 크롤링하지 못하게 함)
- ❌ hreflang 태그 누락 (중복 콘텐츠 문제 발생)
- ❌ 언어 간 URL 구조 불일치
- ❌ 번역되지 않은 메타 태그
번역 품질
AI 번역 vs 인간 번역:
- ✅ AI: 빠르고 비용 효율적이며 초안에 적합
- ⚠️ AI: 문화적 뉘앙스를 놓칠 수 있음, 검토 필요
- ✅ 인간: 더 나은 품질, 문화 적응
- ⚠️ 인간: 느리고 비용이 많이 듦
권장 접근 방식:
- AI를 사용하여 초기 번역 생성
- 원어민이 검토 및 개선
- 타겟 시장 사용자와 테스트
- 피드백을 바탕으로 반복 개선
Next.js i18n 라우팅
이 시스템은 next-intl을 사용한 라우팅을 사용합니다:
- URL에서 자동 로케일 감지
- 언어 전환기 컴포넌트
- 지역화된 탐색
구성은 i18n/locale.ts 및 i18n/request.ts에 있습니다.
국제화 후 작업
언어를 추가한 후:
- Google Search Console에 업데이트된 사이트맵 제출
- 언어/지역별로 별도의 Search Console 속성 생성
- Analytics에서 국제 유기적 트래픽 모니터링
- 언어별 전환율이 다른 경우 A/B 테스트
- 국제 크롤링 오류에 대한 알림 설정
스크립트 위치
모든 i18n 스크립트는 scripts/ 디렉토리에 있습니다:
i18n-add-languages.mjs- 새 언어 파일 추가i18n-add-schema.js- 구조화된 데이터 번역 추가
참고 자료
- WORKFLOW.md - 상세 단계별 워크플로우
- reference/hreflang-guide.md - hreflang 구현 가이드
- reference/locale-codes.md - 언어 코드 참조
- reference/seo-checklist.md - 국제 SEO 체크리스트
문제 해결은 WORKFLOW.md의 문제 해결 섹션을 참조하세요.