HTML

원본 소스에서 번역하지 않는 부분은 그대로 보존하면서 HTML 텍스트와 속성을 번역하고, 문서 언어를 대상 로캘로 설정합니다.

HTML은 링크, 동작, 접근성 정보를 담은 구조 안에 사람이 읽을 수 있는 텍스트를 배치합니다. html 핸들러는 지원되는 텍스트 구간과 설명용 속성을 선택한 뒤, 하나의 대상 로캘에 맞춘 번역을 원본 소스에 반영합니다. 다국어 페이지를 로캘별 영역으로 나누지는 않습니다.

입력 문서의 구조 유지 #

문서는 원래의 문서 유형 선언과 명시적으로 작성된 요소를 유지합니다. 문서 조각은 그대로 유지되며, 번역 과정에서 <html>, <head>, <body> 래퍼를 추가하지 않습니다. 주석, 수정하지 않은 속성, 따옴표 형식, 번역 구간 밖의 공백은 소스에 작성된 그대로 보존됩니다.

명시적으로 작성된 <html> 요소가 있으면 기존 lang 값을 대상 로캘로 바꾸고, 해당 속성이 없으면 lang 속성을 추가합니다. 예를 들어 프랑스어로 번역하면 <html lang="en">가 <html lang="fr">로 바뀝니다. 명시적인 <html> 요소가 없는 문서 조각에는 언어 지정만을 목적으로 해당 요소를 추가하지 않습니다.

예를 들어 다음 문서 조각에는 화면에 표시되는 문구와 접근성 텍스트가 포함되어 있습니다.

html
<section>
  <h2>Delivery options</h2>
  <p>Read the <a href="/delivery">delivery policy</a>.</p>
  <img src="/truck.svg" alt="Delivery truck" />
  <input placeholder="Enter your address" aria-label="Delivery address" />
</section>

제목, 문단, 링크 레이블, 이미지 대체 텍스트, 입력 필드의 자리표시자, ARIA 레이블은 번역이 지원되는 텍스트입니다. 링크 대상과 이미지 소스는 구조적 속성으로 그대로 유지됩니다. 이 문서 조각을 번역해도 현지화된 링크를 생성하거나 이미지 자산을 교체하지는 않습니다.

속성 및 영역 선택 #

기본으로 지원되는 속성에는 이미지의 alt 및 title, 입력 필드와 텍스트 영역의 placeholder 및 title, 일부 title 속성, 메타 content, ARIA 레이블 속성이 있습니다. 메타데이터는 꼼꼼히 점검하세요. 속성을 이름으로 선택했다고 해서 그 값이 모두 일반 문장인 것은 아닙니다. 컴포넌트 속성 규칙을 설정하면 이름이 지정된 요소에서 추출할 속성을 추가할 수 있습니다.

스크립트, 스타일, 서식이 유지되는 코드, 코드, 수식, 템플릿, 스크립트 미지원 시 표시되는 콘텐츠, 텍스트 영역의 내용은 일반 텍스트 추출 대상에서 제외됩니다. 제외된 요소에도 지원되는 설명용 속성은 있을 수 있습니다. SVG는 임의의 그리기 데이터를 번역하지 않고, 전용 선택 방식을 통해 지원되는 title, desc, text 콘텐츠를 추출합니다.

텍스트를 번역하는 동안 인라인 마크업과 {{...}} 토큰은 자리표시자로 보호되며, 재구성 과정에서 번역된 구간 안에 복원됩니다. 결과의 요소 구조를 확인하고, 애플리케이션에서 사용하는 대표적인 값을 변수에 넣어 렌더링하세요.

재사용 및 원본 소스를 보존하는 출력 #

이전 번역을 재사용하려면 이전 소스와 번역문의 텍스트 및 자리표시자 구조가 서로 대응해야 합니다. 핸들러는 이 대응 관계를 확인하며, 관계가 모호한 소스와 번역문 쌍은 거부할 수 있습니다. 서로 무관한 렌더링 페이지를 비교하기보다는, 승인된 번역문을 해당 소스 버전과 연결해 보관하세요.

번역된 구간과 명시적으로 작성된 <html> 요소의 언어 속성만 바뀌며, 나머지 소스는 결과에 그대로 복사됩니다. 핸들러는 신뢰할 수 없는 HTML에서 유해한 내용을 제거하지 않습니다. 애플리케이션 자체의 보안 및 렌더링 검사는 그대로 유지하세요.

잘못된 중첩 때문에 파서가 서로 무관한 마크업의 텍스트를 하나로 합치면, 핸들러는 모호한 번역문을 작성하는 대신 문서를 거부합니다. 중첩을 바로잡은 뒤 다시 시도하세요. HTML 규칙상 생략이 허용되는 태그 때문에 문서의 기본 구조를 추가할 필요는 없습니다.

CLI 또는 GitHub App에서 HTML 파일 설정 #

CLI 및 GitHub App은 .html와 .htm를 바탕으로 html를 추론합니다. .lingo/config.json에서 소스 파일을 선택하되, 생성된 번역 파일이 소스 패턴에 포함되지 않도록 하세요:

json
{
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    { "pattern": "pages/en/**/*.html", "format": "html" },
    { "pattern": "pages/en/**/*.htm", "format": "html" }
  ]
}

이 확장자에서는 format를 명시하지 않아도 됩니다. CLI 설정을 통해 프로젝트를 조직 및 로컬라이제이션 엔진에 연결하거나, GitHub App에서 사용할 엔진을 지정하세요. 각 번역 결과는 pages/fr/index.html와 같은 별도의 로캘 파일로 생성됩니다. HTML은 키 단위 번역을 지원하지 않습니다.

결과를 가져온 뒤에는 실제로 사용하는 환경에서 문서나 문서 조각을 렌더링하세요. 링크와 텍스트가 아닌 속성을 비교하고, 화면에 표시되는 문구와 접근성 텍스트를 함께 점검하세요. 콘텐츠 관리 시스템에서 HTML을 제공한다면 해당 커넥터의 필드 선택 및 결과 쓰기 지침을 따르세요. 내부 구현에 HTML 처리가 포함되어 있더라도 커넥터마다 허용하는 입력은 다를 수 있습니다.