회고 & 컬럼/쿠고랑 개발일지

kugorang/pokat 단일 HTML 구조로 3개 언어 전환과 24컷 WebP 지연 로딩 구현하기

kugorang 2026. 11. 18. 00:23

TL;DR

  1. kugorang/pokat 저장소(pokat.kugora.ng)는 빌드 도구나 자바스크립트 프레임워크 없이 index.html(338줄, 23,015 Bytes)과 assets/site.css(582줄, 9,229 Bytes)만으로 한국어, 영어, 일본어를 즉시 전환한다.
  2. 언어별 HTML 파일을 3벌 복제하지 않고 <html>의 data-language 속성과 CSS 선택자 4줄로 노출을 제어하며, 35줄짜리 인라인 스크립트가 URLSearchParams, localStorage, 버튼의 aria-pressed, 이미지의 alt 속성까지 한 번에 바꾼다.
  3. 2026-11-17 커밋(bcb94d6)에서 24개 WebP 스티커(01.webp~24.webp, 총 3,623,280 Bytes)를 일괄 교체할 때 HTML과 CSS를 한 줄도 고치지 않고도, width="240" height="240" 고정과 loading="lazy" 지연 로딩을 그대로 유지했다.


왜 언어별 페이지를 나누지 않고 단일 HTML 구조를 선택했는가

직전 82호 글에서 다룬 hw.kugora.ng 정적 빌더는 7개 언어마다 별도 HTML 경로를 생성했다. 여러 페이지에 걸친 회사 소개 사이트는 검색 엔진이 언어별 URL을 따로 색인해야 하므로 빌드 시점에 HTML을 나누는 편이 맞다. 반면에 포근한 고양이, 포캣 (pokat.kugora.ng)은 App Store에 출시한 iMessage 스티커 앱 1종을 소개하고 문의 경로와 개인정보 안내를 제공하는 단일 목적 페이지다.

페이지 수가 2개(index.html, privacy.html)뿐인 앱 지원 사이트에서 언어마다 HTML 파일을 따로 복제하면 문구 하나를 고칠 때도 파일 3개를 함께 열어야 한다. 그래서 쿠고랑 (kugorang)은 문구 3개 언어를 한 파일 안에 넣고 브라우저가 화면에 보여 줄 언어만 고르게 만들었다.

실제로 측정한 저장소의 파일 크기와 줄 수는 아래 표에 정리했다.

구성 요소 파일 수 크기 (Bytes) 역할
index.html 1개 (338줄) 23,015 한국어, 영어, 일본어 본문 및 35줄 전환 스크립트
assets/site.css 1개 (582줄) 9,229 언어 숨김 규칙, 4열/6열 반응형 그리드, 다크 모드
privacy.html 1개 3,970 개인정보처리방침 한국어 전문 및 영어 요약
assets/stickers/01~24.webp 24개 3,623,280 (평균 150,970) iMessage 스티커 24컷 아트워크

초기 화면을 그릴 때 브라우저가 반드시 받아야 하는 파일은 index.html과 assets/site.css 두 개뿐이며 합계 크기는 32,244 Bytes(약 31.5 KB)다. 외부 자바스크립트 라이브러리나 CDN 요청이 없어서 네트워크 왕복 횟수가 줄어들고 초기 렌더링이 빨라진다.


CSS 선택자 4줄과 35줄 스크립트로 동작하는 즉시 다국어 전환 원리

다국어 웹사이트를 처음 만들 때 흔히 겪는 문제는 두 가지다. 첫째, 자바스크립트가 모든 문장의 textContent를 일일이 찾아 바꾸는 방식은 HTML 태그가 섞인 문장(예: 링크 <a>가 들어간 문장)을 다룰 때 코드가 급격히 복잡해진다. 둘째, 단순히 글자를 투명하게(opacity: 0) 만들거나 화면 밖으로 치우는 방식은 시각장애인용 화면 낭독기(스크린 리더)가 숨겨진 외국어 문장까지 순서대로 읽어 버리는 문제를 일으킨다.

pokat.kugora.ng는 이 문제를 해결하기 위해 HTML 요소에 언어 이름표를 붙이고 CSS의 display: none으로 숨기는 방식을 사용한다.

1단계: 본문에 data-lang과 lang 속성을 함께 붙인다

각 문단과 목록 안에는 한국어, 영어, 일본어 블록을 나란히 적고, 두 가지 속성을 함께 달아 둔다. data-lang은 CSS가 화면 노출 여부를 가르는 기준이고, lang은 브라우저가 각 언어에 맞는 기본 글꼴과 발음 규칙을 고르도록 돕는 표준 속성이다.

<h1 id="hero-title">
  <span data-lang="ko" lang="ko">포근한 고양이, 포캣</span>
  <span data-lang="en" lang="en">Cozy Pocket Cat, Pokat</span>
  <span data-lang="ja" lang="ja">ポキャット ほっこりポケットねこ</span>
</h1>

2단계: CSS 선택자 4줄로 선택되지 않은 언어를 완전히 숨긴다

assets/site.css의 28~33번째 줄에는 아래 4줄의 선택자만 들어 있다. 루트 <html> 태그의 data-language 값이 "en"이면 [data-lang="en"]을 제외한 나머지 모든 [data-lang] 요소가 display: none !important가 된다. display: none이 적용된 요소는 화면 영역을 차지하지 않고 스크린 리더의 읽기 트리에서도 제외된다.

html:not([data-language]) [data-lang]:not([data-lang="ko"]),
html[data-language="ko"] [data-lang]:not([data-lang="ko"]),
html[data-language="en"] [data-lang]:not([data-lang="en"]),
html[data-language="ja"] [data-lang]:not([data-lang="ja"]) {
  display: none !important;
}

3단계: 35줄 스크립트가 초기 언어 판별과 이미지 alt 치환까지 처리한다

텍스트만 바뀌고 버튼 상태나 이미지 설명(alt)이 한국어로 남아 있으면 다른 언어 사용자가 불편을 겪는다. index.html 하단의 인라인 스크립트(305~336줄)는 페이지를 열 때와 언어 버튼을 누를 때 아래 순서대로 4가지 상태를 한 번에 맞춘다.

(() => {
  const root = document.documentElement;
  const buttons = document.querySelectorAll('[data-switch]');
  const valid = lang => ['ko', 'en', 'ja'].includes(lang);

  document.querySelectorAll('img[data-alt-en]').forEach(img => {
    img.dataset.altKo = img.alt;
  });

  function setLanguage(lang, remember) {
    if (!valid(lang)) lang = 'ko';
    root.lang = lang;
    root.dataset.language = lang;
    buttons.forEach(button => {
      button.setAttribute('aria-pressed', String(button.dataset.switch === lang));
    });
    document.querySelectorAll('img[data-sticker]').forEach(img => {
      const prefix = { ko: '포캣 스티커 ', en: 'Pokat sticker ', ja: 'ポキャット ステッカー ' };
      img.alt = prefix[lang] + img.dataset.sticker;
    });
    document.querySelectorAll('img[data-alt-en]').forEach(img => {
      img.alt = img.getAttribute('data-alt-' + lang);
    });
    if (remember) {
      try { localStorage.setItem('pokat-language', lang); } catch (_) {}
    }
  }

  buttons.forEach(button => {
    button.addEventListener('click', () => setLanguage(button.dataset.switch, true));
  });

  const query = new URLSearchParams(location.search).get('lang');
  let saved = null;
  try { saved = localStorage.getItem('pokat-language'); } catch (_) {}
  setLanguage(valid(query) ? query : valid(saved) ? saved : 'ko', valid(query));
})();

이 코드에서 눈여겨볼 세부 구현은 세 가지다.

  1. 쿼리 파라미터 우선순위: 링크에 https://pokat.kugora.ng/?lang=en 형식으로 언어 코드가 붙어 들어오면 localStorage에 저장된 이전 언어보다 URL 값을 먼저 따르고, 그 값을 localStorage에도 기록한다.
  2. 시크릿 모드 방어: 일부 브라우저 환경에서는 localStorage 접근 시 보안 예외가 발생할 수 있다. 읽기와 쓰기를 모두 try/catch로 감싸서 저장소가 막혀 있어도 언어 전환 스크립트가 멈추지 않게 했다.
  3. 이미지 alt 동시 갱신: 페이지가 처음 열릴 때 한국어 기본 alt를 data-alt-ko에 복사해 두고, 이후 언어가 바뀔 때마다 로고 2개와 스티커 24개의 alt 문자열을 즉시 갈아 끼운다.

24컷 WebP 스티커 갤러리 렌더링 최적화와 에셋 교체 검증

스티커 소개 페이지에서 가장 무거운 자원은 글자가 아니라 이미지다. 24개 WebP 스티커의 크기를 전부 합하면 3,623,280 Bytes(약 3.46 MB)이며, 파일별 크기는 최소 113,120 Bytes(15.webp)에서 최대 179,934 Bytes(02.webp) 사이다.

이 이미지 24장을 페이지가 열리자마자 한꺼번에 받아 버리면, 첫 화면에 있는 앱 아이콘(icon-256.png)과 다운로드 버튼이 늦게 뜰 수 있다. index.html은 우선순위를 나누어 이 문제를 해결한다.

  • 첫 화면 히어로 아이콘: fetchpriority="high"와 decoding="async"를 붙여 다른 이미지보다 먼저 내려받게 한다.
  • 24개 스티커 그리드: 모든 <img> 태그에 loading="lazy"와 decoding="async"를 넣어, 사용자가 스크롤을 내려 스티커 영역에 가까워졌을 때만 이미지를 내려받는다.
  • 고정 크기와 비율: 모든 스티커 이미지에 width="240" height="240"을 적고 CSS에서 aspect-ratio: 1과 object-fit: contain을 지정한다. 이미지 파일이 아직 도착하기 전에도 브라우저가 정사각형 칸을 미리 비워 두므로, 이미지가 뒤늦게 뜨면서 아래쪽 설명 글이 밀려 내려가는 현상(CLS)이 생기지 않는다.

그리드 배치와 색상 접근성도 같은 CSS 파일 안에서 단순한 규칙으로 처리한다.

  • 반응형 열 수 전환: 기본 모바일 화면에서는 grid-template-columns: repeat(4, minmax(0, 1fr))로 가로 4열(6줄)을 만들고, 화면 너비가 760px 이상이 되면 repeat(6, minmax(0, 1fr))로 가로 6열(4줄)로 자동 전환한다.
  • 다크 모드와 모션 최소화: @media (prefers-color-scheme: dark)로 배경(#241f1c)과 글자(#fff0de) 대비를 바꾸고, @media (prefers-reduced-motion: reduce)가 켜진 기기에서는 스크롤 이동 애니메이션과 전환 효과를 끄도록 작성했다.

2026-11-17 커밋(bcb94d6, "Refresh all website stickers with approved v5 artwork")에서는 24개의 스티커 파일(01.webp~24.webp)을 전부 새 아트워크로 바꿨다. 이때 HTML이나 CSS를 한 줄도 고치지 않고 이미지 파일만 교체할 수 있었던 이유는 파일 경로(01.webp부터 24.webp까지)와 정사각형 비율 규칙을 코드와 분리해 고정해 두었기 때문이다.

쿠고랑 (kugorang) 개발 원칙에서 코드 수정과 모의 시험 통과, 실기기 검증, 운영 반영은 서로 다른 단계다. 로컬 저장소에서 파일을 바꾼 뒤에는 실제 배포 주소(https://pokat.kugora.ng/와 https://pokat.kugora.ng/assets/stickers/01.webp)가 HTTP 200 응답과 바뀐 바이트 크기(23,015 B, 140,890 B)를 반환하는지 확인해야 운영 반영이 끝난다.


자주 묻는 질문 (FAQ)

Q1. HTML 파일 하나에 3개 언어를 모두 넣으면 파일이 너무 커지지 않나요?

짧은 앱 소개 페이지에서는 그렇지 않다. pokat.kugora.ng의 index.html은 3개 언어 문구와 스크립트를 모두 합쳐도 23,015 Bytes(약 22.5 KB)다. 이미지 파일 1장 평균 크기(150,970 Bytes)의 6분의 1 수준이라 초기 로딩 속도에 부담을 주지 않으며, 문구 수정 시 파일 1개만 관리하면 되는 이점이 크다.

Q2. 검색 엔진(SEO)이 영어나 일본어 키워드로 검색했을 때도 이 페이지를 제대로 찾나요?

단일 URL에 모든 언어 텍스트가 들어 있으므로 검색 엔진 크롤러가 한 번의 방문으로 한국어, 영어, 일본어 텍스트를 모두 읽는다. 다만 영어 전용 URL(/en/)이나 일본어 전용 URL(/ja/)을 검색 결과에 분리해서 띄워야 하는 대형 서비스라면, 직전 82호에서 다룬 정적 빌더 방식에서 언어별 경로를 나누는 구조가 알맞다.

Q3. 왜 visibility: hidden 대신 display: none !important를 썼나요?

visibility: hidden은 글자를 투명하게 가릴 뿐 화면의 빈 공간은 그대로 차지하며, 브라우저나 보조공학 기기 설정에 따라 문서 흐름 해석에 혼선을 줄 수 있다. display: none !important를 적용하면 선택되지 않은 언어 요소의 공간이 완전히 사라지고 화면 낭독기도 현재 선택된 언어만 또렷하게 읽는다.


출처:

  • https://github.com/kugorang/pokat
  • https://pokat.kugora.ng/
728x90
728x90