국제화 (i18n)
Apothem 문서 사이트가 로케일 코호트를 선언하고, hreflang 대체 언어 링크를 내보내며, 우→좌 렌더링을 처리하고, 번역 공백을 정직하게 드러내는 방식.
이 페이지는 Apothem 문서 사이트가 여러 언어를 처리하는 방식을 설명합니다.
선언하는 로케일 코호트, 내보내는 hreflang 메커니즘, 우→좌 준비 상태, 그리고
로케일별 번역의 정직한 현황입니다.
결정 요약
- 플랫폼: Next.js App Router + Fumadocs. 사이트는
site/로부터 빌드됩니다. 로케일 코호트는site/lib/i18n.ts에 선언되고, 대체 언어 링크 메커니즘은site/lib/hreflang.ts에 있습니다. - 로케일 코호트: 선언됨. 열두 개 로케일로 구성된 Modern Dev Cohort가 정식 진실 공급원으로 선언되며, 영어가 소스 로케일입니다.
- 로케일별 라우팅: 아직 활성화 안 됨. 영어 콘텐츠만 존재하는 상태에서 코호트 전체에 로케일 접두 라우트를 활성화하면, 영어 소스로 조용히 폴백되는 콘텐츠 없는 열한 개 라우트가 생깁니다. 이는 i18n 규율이 금지하는 종류의 조용한 영어 전용 드리프트이므로, 검수된 번역 콘텐츠가 도착할 때까지 라우팅은 단일 로케일로 유지됩니다.
hreflang메커니즘: 활성. 모든 페이지는 작성된 콘텐츠가 있는 각 로케일을 포괄하는<link rel="alternate">집합과x-default폴백을 내보냅니다. 아직 번역을 기다리는 로케일은 생략됩니다 — 영어 폴백을 가리키지 않습니다 — 그래서 검색 엔진에 번역이 존재하지 않음을 정확히 알립니다.- 우→좌 준비: 완료. 공유 스타일시트는 전반적으로 논리적 CSS 속성을
사용하므로, 아랍어 콘텐츠가 도착하면 아랍어 페이지가
dir="rtl"하에서 올바르게 렌더링됩니다. - 기계 번역 정책: 미검수 출시 없음. 어떤 기계 번역 페이지 산문도 게시되지 않습니다. 번역은 기계로 시드되고 어떤 로케일이 번역됨으로 표시되기 전에 사람 검수에 의해 게이트됩니다.
로케일 코호트
Modern Dev Cohort는 열두 개 로케일을 선언합니다. 영어는 사이트 루트에서 제공됩니다. 열한 개 대상은 스택이 국제화 준비되도록 하고 번역 공백을 조용한 것이 아니라 명시적인 것으로 만들기 위해 선언됩니다.
| 코드 | 경로 | 언어 | 방향 | 콘텐츠 |
|---|---|---|---|---|
en | / | 영어 | LTR | 번역됨 (소스) |
zh-CN | /zh-cn/ | 중국어 간체 | LTR | 대기 중 |
es | /es/ | 스페인어 | LTR | 대기 중 |
pt-BR | /pt-br/ | 브라질 포르투갈어 | LTR | 대기 중 |
fr | /fr/ | 프랑스어 | LTR | 대기 중 |
de | /de/ | 독일어 | LTR | 대기 중 |
ja | /ja/ | 일본어 | LTR | 대기 중 |
ko | /ko/ | 한국어 | LTR | 대기 중 |
ru | /ru/ | 러시아어 | LTR | 대기 중 |
id | /id/ | 인도네시아어 | LTR | 대기 중 |
ar | /ar/ | 아랍어 | RTL | 대기 중 |
hi | /hi/ | 힌디어 | LTR | 대기 중 |
코호트는 단일 진실 공급원입니다. 그에 대한 수정은 조용한 편집이 아니라 신중한 결정을 거쳐 이루어집니다.
hreflang이 작동하는 방식
site/lib/hreflang.ts는 Next.js가 각 페이지의 <head>로 렌더링하는
alternates.languages 맵을 구축합니다. 그 구성은 하나의 규칙을 지킵니다.
로케일의 대체 언어 링크는 그 로케일에 작성된 콘텐츠가 있을 때만
내보냅니다. 오늘날 영어가 유일하게 번역된 로케일이므로, 모든 페이지는 정확히
두 개의 링크를 내보냅니다:
<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />페이지의 canonical 링크는 항상 자신의 URL입니다 — 결코 로케일을 가로질러
가리키지 않습니다. 어떤 로케일의 콘텐츠가 도착하고 site/lib/i18n.ts에서 그
상태가 번역됨으로 전환되면, 그 로케일의 hreflang 링크가 자동으로
내보내지기 시작하고, 동일한 변경 세트에서 로케일별 라우팅이 활성화됩니다.
우→좌 렌더링
아랍어는 코호트의 우→좌 로케일입니다. 사이트는 그것에 대비되어 있습니다:
- 논리적 CSS 속성만 사용. 공유 스타일시트와 컴포넌트는 물리적 속성
(
margin-left,text-align: left)이 아닌 논리적 속성 (margin-inline-start,padding-inline-end,text-align: start,inset-inline-start)을 사용합니다. 논리적 속성은dir="rtl"하에서 자동으로 뒤집히므로, 동일한 스타일시트가 양방향을 올바르게 제공합니다. - 방향 속성. 아랍어 콘텐츠가 도착하면 아랍어 페이지는
<html>요소에lang="ar"와 함께dir="rtl"을 설정합니다. - 양방향 콘텐츠. 방향이 혼합된 문자열 — 예를 들어 아랍어 단락 안의 영어
커맨드 — 은
<bdi>로 감싸서 임베드된 좌→우 구간이 우→좌 흐름 안에서 올바르게 렌더링되도록 합니다.
번역 추가하기
사이트를 코호트 로케일로 번역하려면:
- 그 로케일에 대한 검수된 번역 페이지를 작성합니다.
site/lib/i18n.ts에서 그 로케일의 콘텐츠 상태를 번역됨으로 전환합니다.- 그
hreflang링크가 내보내지기 시작하고 라우트가 도달 가능해집니다.
어떤 로케일의 번역이 작성되고 검수될 때까지 영어 페이지를 진실 공급원으로 유지하십시오. 어떤 기계 번역 콘텐츠도 미검수로 출시되지 않습니다.
현재 상태와 번역된 코퍼스로 가는 경로
오늘날 사이트는 국제화 준비가 되어 있지만 콘텐츠는 영어 전용입니다. 인프라 —
코호트 선언, hreflang 메커니즘, 논리적 CSS 우→좌 준비 — 는 갖추어져
있습니다. 로케일별 번역된 코퍼스는 아직 없습니다. 완전히 번역된 코퍼스는
기능 등급 작업입니다. 각 로케일의 페이지는 기계로 시드된 뒤 사람이 검수하며,
릴리스는 각 로케일이 검수 임계값을 통과한 뒤에야 국제화 프로덕션 준비가
됩니다. 그때까지 코호트는 선언되어 있고, 공백은 보이며, 미검수 번역은 출시되지
않습니다.