언어 협상은 /에서만 수행하고, /en/ 및 /fr/ 같은 명시적 URL은 항상 해당 언어로 제공하세요. 이 가이드는 Mac 데스크톱 게시자가 이 동작을 지정하고, 검색 가능한 문서 링크를 유지하며, 결과를 테스트하는 방법을 보여줍니다.

예제에서는 도형 배치에 관한 짧은 안내문의 영어 및 프랑스어 버전이 있는 가상의 공개 문서 모음을 사용합니다. 이 모음의 루트는 요청에 따라 소개 문구를 바꿀 수 있는 언어 선택 페이지입니다. 예시 주소는 제안된 구성을 설명하며, 해당 주소에 현재 호스팅되는 페이지가 있다는 뜻은 아닙니다.

언어 설정을 바꾸기 전에 URL 동작 정의하기

먼저 간단한 라우팅 규칙을 정하세요. 이 예제에서 루트는 독자가 언어를 선택하도록 돕고, 두 개의 명시적 경로에는 번역된 문서 전체가 들어 있습니다. Google은 언어 버전마다 별도 URL을 사용할 것을 권장하며, 추정한 언어를 바탕으로 독자를 버전 간에 자동 리디렉션하지 말라고 안내합니다. 눈에 보이는 링크를 통해 독자가 직접 선택할 수 있습니다. 다지역 및 다국어 사이트 관리하기.

요청 경로 의도한 응답 언어 기본 설정의 영향
/ 짧은 소개가 있는 언어 선택기 소개 문구와 추천 링크가 바뀔 수 있음
/en/ 영어 문서 전체 문서 언어가 바뀌지 않음
/fr/ 프랑스어 문서 전체 문서 언어가 바뀌지 않음
공개되지 않은 경로 페이지 없음 응답 다른 문서로 조용히 바뀌면 안 됨

이 표를 구현 요건으로 삼으세요. 요청이 루트를 대상으로 하는지 확인한 다음에만 언어 선택을 적용하세요. 모든 페이지 요청보다 먼저 실행되는 일반 규칙은 명시적 선택을 덮어써 이 규칙을 깨뜨릴 수 있습니다.

예를 들어 /fr/를 따라온 사용자는 요청에서 영어를 선호한다고 해도 프랑스어 문서를 받아야 합니다. 영어 선호는 아직 선택하지 않은 진입점에서 유용하지만, 다른 곳에서는 명시적 경로가 이미 선택을 나타냅니다. 이 우선순위는 이 글 전체에서 사용하는 설계 권장 사항입니다.

모든 페이지에서 두 언어 링크를 모두 표시하세요. 루트에서는 다른 선택지를 숨기지 않으면서 추천 언어로 첫 선택을 쉽게 할 수 있습니다. 문서 전체가 표시되는 페이지에서는 언어 전환 링크가 대응하는 문서로 바로 이동해야 합니다.

예측 가능한 루트 언어 정책 선택하기

Accept-Language는 fr;q=0.9,en;q=0.5 같은 품질 가중치를 포함해 선호하는 응답 언어를 나타냅니다. 서버가 요청된 모든 언어를 제공해야 한다는 뜻은 아닙니다. 품질 값이 0이면 허용되지 않는 언어입니다. Content-Language는 반환된 표현의 대상 독자를 설명하며, 경로를 선택하지는 않습니다. RFC 9110: HTTP 의미론, 8.5절, 12.4.2절 및 12.5.4절.

무엇을 설정하기 전에 지원 언어 목록과 대체 동작을 문서화하세요. 이 예제에서는 영어와 프랑스어 소개 문구를 사용합니다. 요청에 사용할 수 있는 일치 항목이 없으면 영어 소개 문구와 두 언어 선택지를 모두 표시합니다. 이 대체 동작은 예시 게시 정책이며 HTTP 요구 사항은 아닙니다.

명시적인 정책을 적용하는 언어 일치 구현을 사용하세요. RFC 4647은 필터링과 조회를 구분합니다. 조회는 하나의 결과를 선택하고, 우선순위가 높은 요청 범위부터 고려하며, 일치 항목을 찾을 때 하위 태그를 단계적으로 제거합니다. 또한 조회를 사용하는 애플리케이션은 기본 동작을 정의해야 합니다. 따라서 fr-CA 요청은 조회를 통해 지원되는 일반 fr 소개 문구로 연결될 수 있습니다. RFC 4647: 언어 태그 일치, 3.4–3.4.1절.

헤더에서 fr 또는 en가 처음 나오는 위치를 찾아 언어를 선택하지 마세요. 이런 간편한 방식은 가중치와 제외 항목을 놓칩니다. 일치 처리 계층은 선호도를 파싱하고, 가중치가 0인 제외 항목을 반영한 다음, 문서화된 대체 동작을 적용해야 합니다.

루트 요청의 언어 선호도 이 예제의 예상 결과
헤더 없음 영어 소개 문구와 두 언어 선택지
fr 프랑스어 소개 문구와 두 언어 선택지
fr-CA,fr;q=0.9,en;q=0.5 프랑스어 소개 문구
en;q=0.9,fr;q=0.2 영어 소개 문구
de 대체 언어 선택기
fr;q=0,en;q=1 영어 소개 문구. 프랑스어는 선택되지 않음
*;q=0 일치하지 않는 언어에 대해 명시적으로 정의한 처리 방식

마지막 행은 의도적으로 결정해야 합니다. 이 선택기 설계에서는 애플리케이션이 해당 선호도를 따르지 않으므로, 제외된 언어만 요청된 경우 대체 언어 선택기를 표시한다고 지정하세요. 영어가 일치했다고 주장해서는 안 됩니다. 엄격한 협상이 필요하다면 이에 해당하는 허용 불가 응답 동작을 정의하고 테스트하세요. 어느 경우든 값 0을 일반적인 낮은 선호도로 잘못 처리하지 마세요.

문서 언어, 링크 및 검색 주석을 일치시키기

각 HTML 문서에서 lang 속성을 실제 기본 언어로 설정하세요. 영어 페이지에는 en, 프랑스어 페이지에는 fr을 사용합니다. WHATWG는 lang를 요소 콘텐츠와 텍스트를 포함하는 속성의 기본 언어로 정의하며, 속성값을 생략하면 부모 요소에서 상속합니다. 경로 접두사만으로는 이 언어 선언을 대신할 수 없습니다. HTML 표준: lang 및 xml:lang 속성.

페이지 텍스트뿐 아니라 탐색 링크도 확인하세요. WHATWG URL 표준에 따르면 상대 URL은 기본 URL을 기준으로 해석됩니다. 예를 들어 별도의 문서 기본 URL이 없으면 https://example.com/en/에서 fr/는 https://example.com/en/fr/로 해석되고, /fr/는 해당 출처의 프랑스어 경로로 연결됩니다. 화면에 표시되는 전환 링크에는 의도한 절대 경로를 사용하세요. URL 표준: URL 작성 및 파싱.

검색 주석은 별도의 목적을 수행합니다. Google은 HTML, HTTP 헤더 또는 사이트맵을 통한 동등 언어 주석을 지원합니다. 관리하기 쉬운 방법 하나를 선택하세요. 각 버전은 전체 URL로 자신과 대응 문서를 지정해야 하며, 주석을 통해 버전끼리 서로 연결해야 합니다. 루트 선택기는 x-default 대상으로 사용할 수 있습니다. 페이지의 현지화 버전을 Google에 알리기.

가상의 문서 모음에서 주석 매핑은 다음과 같습니다.

주석 가상의 대상 URL
en https://example.com/en/
fr https://example.com/fr/
x-default https://example.com/

게시 시스템이 지원하는 주석 방식으로 이 관계를 입력하세요. 이 매핑은 사양이지 실행 가능한 마크업이 아닙니다. x-default은 서버 협상을 구성하거나 번역을 제공하지 않습니다. 또한 Google은 페이지 언어를 알고리즘으로 판별하며, 언어 감지에 hreflang이나 HTML lang를 사용하지 않는다고 설명합니다. 페이지의 현지화 버전을 Google에 알리기.

루트의 언어별 적응 동작에 의존하지 않고도 완전한 번역본에 각각 접근할 수 있게 하세요. Google은 크롤러가 Accept-Language 없이 요청을 보내며, 지역별 적응 페이지는 일부 변형 버전이 발견되지 않을 수 있다고 경고합니다. 신뢰할 수 있는 대체 동작과 직접적인 언어별 URL을 제공하면 크롤러가 다른 루트 소개 문구를 요청하지 않아도 검색 가능성 문제를 해결할 수 있습니다. Google이 지역별 적응 페이지를 크롤링하는 방식.

캐시된 루트 응답이 언어 선택을 따르게 하기

루트 선택이 Accept-Language에 따라 달라진다면 대체 응답을 포함한 루트 응답에 Vary: Accept-Language를 포함하세요. 기존의 다른 변형 필드는 유지합니다. 프랑스어 루트 응답 예시에는 아래 헤더 조각이 포함됩니다. 완전한 HTTP 메시지는 아닙니다. RFC 9110: HTTP 의미론, 12.5.5절.

Content-Type: text/html; charset=utf-8
Content-Language: fr
Vary: Accept-Language

RFC 9111은 저장된 응답을 재검증 없이 재사용하기 전에 캐시가 Vary에 지정된 요청 필드와 일치하는지 확인하도록 요구합니다. 루트 URL은 그대로인데 소개 문구가 바뀌므로 이 점이 중요합니다. Vary는 선택 입력을 설명할 뿐 언어 일치 기능을 구현하지 않습니다. RFC 9111: HTTP 캐싱, 4.1절.

이 설계에서는 /en/과 /fr/의 문서가 Accept-Language에 따라 달라지지 않습니다. 공유 캐시를 포함한 전체 전송 경로가 라우팅 규칙을 따르는지 확인하세요. 실용적인 진단 방법으로 영어와 프랑스어 루트 요청을 번갈아 보내고, 그 순서를 뒤집어 보세요. 루트가 직전에 요청한 언어를 반복해서 반환한다면 캐시 동작과 라우팅을 함께 점검해야 합니다.

Mac에서 규칙 테스트하기

먼저 공개된 데모 출처에 가상의 페이지 세 개를 준비하세요. 아래 테스트는 해당 출처에 /, /en/, /fr/ 경로의 데모 문서 모음만 들어 있다고 가정합니다. 이 테스트는 페이지를 만들거나 호스트를 구성하지 않습니다. 앞서 나온 예시 example.com 주소는 실제로 작동하는 테스트 환경이 아닙니다.

Mac에서 터미널 앱을 열고 curl --version을 실행해 curl을 사용할 수 있는지 확인하세요. 그런 다음 아래의 완전한 셸 진단 스크립트를 붙여 넣으세요. 메시지가 표시되면 경로와 끝의 슬래시 없이 https://를 포함한 데모 출처를 입력하세요.

printf 'Public demo origin, without a trailing slash: '
IFS= read -r demo_origin
case "$demo_origin" in
  https://*) ;;
  *) printf 'Enter an HTTPS origin.\n' >&2; exit 1 ;;
esac

for demo_path in / /en/ /fr/; do
  for demo_language in '' 'en' 'fr' 'fr-CA,fr;q=0.9,en;q=0.5' 'en;q=0.9,fr;q=0.2' 'de' 'fr;q=0,en;q=1'; do
    printf '\nPath: %s | Accept-Language: %s\n' \
      "$demo_path" "${demo_language:-absent}"
    curl --silent --show-error --connect-timeout 5 --max-time 15 \
      --dump-header - --header "Accept-Language: $demo_language" \
      "$demo_origin$demo_path" || exit 1
  done
done

이 진단 스크립트는 응답 헤더와 본문을 출력합니다. curl의 --header는 언어 선호도를 지정하며, 빈 값은 해당 헤더를 제거합니다. --dump-header -는 헤더를 표준 출력에 표시하고, 시간 제한은 각 전송에 상한을 둡니다. 리디렉션 추적 옵션은 의도적으로 생략하여 예상치 못한 리디렉션이 그대로 드러나게 했습니다. curl — 사용 방법.

스크립트의 셸 구문은 확인했지만, 데모 환경을 배포하거나 실제 언어 라우팅 결과를 확인한 것은 아닙니다. curl 전송이 실패하면 스크립트가 중단되지만, HTTP 오류 응답은 출력에 계속 표시될 수 있으므로 직접 검사해야 합니다.

루트 응답을 선호도 표와 비교하세요. 그런 다음 제공한 선호도와 관계없이 각 /en/ 응답에 영어 콘텐츠가 있는지, 각 /fr/ 응답에 프랑스어 콘텐츠가 있는지 확인하세요. 상태 코드, 예상치 못한 Location 필드, 반환된 언어 선언, 실제 문서 텍스트를 점검합니다. 헤더가 올바르더라도 본문이 잘못되면 테스트는 실패한 것입니다.

마지막으로 브라우저에서 두 명시적 URL을 모두 여세요. 각 언어 전환 링크를 따라가고, 대상 페이지를 새로 고친 다음 주소 표시줄을 확인하세요. 이렇게 하면 직접 요청이 성공했을 때 놓칠 수 있는 탐색 오류를 발견할 수 있습니다. 공개되지 않은 경로도 별도로 테스트하여 문서 전체 중 하나를 조용히 표시하지 않는지 확인하세요.

언어 협상을 사용할 수 없을 때 안정적인 선택기 사용하기

이 설계에는 요청 헤더를 읽고 응답을 선택할 수 있는 전송 계층이 필요합니다. WHATWG의 문서 언어 및 URL 기능은 문서와 주소를 설명합니다. lang 속성을 추가하거나 링크 텍스트를 바꿔도 HTTP 협상이 저절로 이루어지지 않습니다. 요청에 따른 선택은 HTTP 전송 설정에서 처리해야 합니다. HTML 표준, RFC 9110: HTTP 의미론.

게시 시스템에 그런 전송 기능이 없다면 완전한 언어별 페이지로 이어지는 직접 링크를 제공하는 고정 루트 선택기를 사용하세요. 그러면 독자가 직접 선택할 수 있고, 별도의 언어별 URL과 눈에 보이는 전환 링크를 사용하라는 Google의 권장 사항도 따르게 됩니다. 여기서는 특정 게시 제품의 협상 기능이 있다고 가정하지 않습니다. 다지역 및 다국어 사이트 관리하기.

실무에서의 승인 기준은 간단합니다. 선호도는 루트에서 도움을 줄 수 있고, 명시적인 언어 링크는 언제나 신뢰할 수 있는 목적지가 되어야 합니다. 문서화된 대체 동작, 일치하는 문서 언어 선언, 상호 연결된 언어 주석, 요청별 라우팅 규칙 준수 증거를 갖추면 됩니다.

출처