김종한의 포트폴리오

Appearance

JSON 검사 스크립트를 만들고 자동화하여 반복적인 휴먼 에러 해결 ​

번역용 JSON 파일을 비교하는 스크립트를 만들고, 스크립트 실행까지 자동화해 반복적으로 발생하던 휴먼 에러를 해결한 경험을 정리했습니다.

휴먼 에러 1. JSON 파일의 키 누락 ​

다국어 지원(i18n) 기능을 구현한 뒤, 한국어, 영어 번역용 JSON 파일에서 키가 누락되어 웹사이트에 텍스트가 제대로 표시되지 않는 문제가 반복적으로 발생했습니다. 원인은 JSON 파일의 키 누락을 사전에 감지하지 못한 휴먼 에러였습니다. 웹사이트에 필요한 JSON 파일을 해외 팀에서 번역해 전달해 주는 구조라, 번역 과정에서 키가 누락되는 일이 종종 발생했습니다. 키 누락 이슈가 생길 때마다 두 JSON 파일을 직접 대조하며 수정하는 과정은 매우 번거롭고 비효율적이었습니다.

파일들을 대조하여 모든 키가 동일한지 확인하는 Node.js 스크립트 작성 ​

그래서 한국어, 영어 JSON을 읽고 파싱하여 모든 키를 비교하여 누락된 키가 있는지 검사하는 Node.js 스크립트를 작성했습니다.

js
/* eslint-disable no-console */
import { readFile } from "node:fs/promises";

const files = ["src/shared/i18n/config/messages/ko.json", "src/shared/i18n/config/messages/en.json"];

const loadJson = async path => {
  try {
    const jsonContent = await readFile(path, "utf8");
    return JSON.parse(jsonContent);
  } catch (error) {
    console.error(`다음 경로의 JSON 파일을 읽거나 파싱하는 중 오류가 발생했습니다: ${path}`, error);
    throw error;
  }
};

const getAllKeys = (obj, parentKey = "") => {
  let keys = [];
  for (const key in obj) {
    const newKey = parentKey ? `${parentKey}.${key}` : key;
    if (typeof obj[key] === "object" && obj[key] !== null) {
      keys = [...keys, ...getAllKeys(obj[key], newKey)];
    } else {
      keys.push(newKey);
    }
  }
  return keys;
};

const checkKeys = async () => {
  let hasError = false;
  const koJson = await loadJson(files[0]);
  const enJson = await loadJson(files[1]);

  const koKeys = getAllKeys(koJson);
  const enKeys = getAllKeys(enJson);

  const koKeysSet = new Set(koKeys);
  const enKeysSet = new Set(enKeys);

  const missingInKo = enKeys.filter(key => !koKeysSet.has(key));
  const missingInEn = koKeys.filter(key => !enKeysSet.has(key));
  console.log("ko.json과 en.json 사이의 누락된 키를 확인하는 중...");

  if (missingInKo.length > 0) {
    hasError = true;
    console.error("ko.json에 누락된 키:", missingInKo);
  } else {
    console.log("ko.json에 누락된 키가 없습니다");
  }

  if (missingInEn.length > 0) {
    hasError = true;
    console.error("en.json에 누락된 키:", missingInEn);
  } else {
    console.log("en.json에 누락된 키가 없습니다");
  }
  if (hasError) globalThis.process.exit(1);
};

try {
  await checkKeys();
  console.log("Locales 체크가 성공적으로 완료되었습니다");
} catch (error) {
  console.error("Locales 체크 중 오류가 발생했습니다:", error);
  globalThis.process.exit(1);
}

package.json에 스크립트를 실행하는 명령어를 등록해 두고, JSON 파일에 새로운 번역 텍스트가 추가될 때마다 이 스크립트를 실행해 검사를 진행했습니다.

휴먼 에러 2. 검사 실행 누락 ​

그런데도 어느 순간 다시 웹사이트에 텍스트가 제대로 표시되지 않는 문제가 발생했습니다. 이번에는 검사 스크립트 실행 자체를 잊어버리는, 또 다른 형태의 휴먼 에러가 문제였습니다. JSON 파일 변경을 감지해, 개발자가 로컬에서 별도로 검사 스크립트를 실행하지 않아도 자동으로 검사가 수행될 필요가 있었습니다.

Lint-staged, Husky 를 활용하여 검사 자동화 ​

lint-staged를 사용해 JSON 파일 변경을 감지하고, Husky를 활용해 검사 스크립트를 Git pre-commit 단계에서 실행하도록 설정했습니다. 이제 번역 누락을 별도로 신경 쓸 필요가 없어졌습니다. 사람이 직접 하던 작업을 스크립트가 대신하면서 에러 발생 횟수도 줄었고, 작업도 훨씬 편리해졌습니다. 반복적이고 번거로운 작업을 자동화하니 휴먼 에러도 줄고, 개발 생산성도 눈에 띄게 올라가는 것을 체감했습니다.