WordPress.org 개발 환경 설정 및 한국어 폰트 적용 가이드 (초보자도 따라 할 수 있게!)

안녕하세요! WordPress.org의 테마 및 플러그인에 한국어 폰트를 적용하고, 관련 개발에 참여하고 싶은 한국인 기여자분들을 위해 최적화된 환경 설정 가이드를 준비했습니다. 이 가이드는 여러 시행착오와 WordPress 메인테이너의 조언을 바탕으로 정리되었으며, 여러분의 소중한 시간을 아껴줄 것입니다.

목표: wporg-main-2022 테마를 중심으로 wporg-parent-2021 (상위 테마) 및 wporg-mu-plugins (필수 플러그인)와 연동하여 한국어 폰트(예: Noto Serif KR, Noto Sans KR)를 적용하고, 안정적인 로컬 개발 환경을 구축합니다.

Issues Discovered While Setting Up Development Environment to Apply Noto Sans/Serif Korean on ko.wordpress.org · WordPress/wporg-mu-plugins · Discussion #690

주요 사용 도구:

• Windows 11 (또는 다른 OS)
• WSL2 (Ubuntu) – Linux 환경 실행
• Git – 버전 관리
• Node.js & Yarn – JavaScript 패키지 관리 및 빌드
• Composer – PHP 패키지 관리
• Docker Desktop – 컨테이너 환경 제공
• @wordpress/env (wp-env) – WordPress 개발 환경 자동 구성 도구
• 텍스트 에디터 (예: VSCode)

---

1단계: 개발 환경 준비

해당 글을 참조해주세요: 워드프레스 개발환경 무작정 따라하기: wp-env – Travel in BUSAN | 부산을 여행하다

1. WSL2 및 Docker Desktop 설치:
   • Windows 사용자라면 WSL2와 Docker Desktop을 설치하여 Linux 기반의 개발 환경을 준비합니다. (각 프로그램 공식 홈페이지의 설치 가이드 참조)
   • Docker Desktop 설정에서 WSL2 백엔드를 사용하도록 설정합니다.
2. 필수 개발 도구 설치 (WSL2 Ubuntu 터미널에서):
   • Git: sudo apt update && sudo apt install git
   • Node.js & Yarn:
     • nvm (Node Version Manager) 설치를 권장합니다. (GitHub nvm-sh/nvm 참조)
     • nvm install --lts (최신 LTS 버전 Node.js 설치)
     • npm install --global yarn (Yarn 설치)
   • Composer: PHP 공식 홈페이지 또는 getcomposer.org의 설치 가이드를 따릅니다.
   • PHP 및 확장 기능: wp-env가 Docker 이미지를 통해 PHP 환경을 제공하므로, 로컬 WSL2에 직접 PHP를 복잡하게 설치할 필요는 없습니다. 다만, Composer 실행 등을 위해 기본적인 PHP CLI는 있는 것이 좋습니다. sudo apt install php-cli php-curl php-mbstring php-xml php-zip

---

2단계: 프로젝트 저장소 복제(Clone) 및 브랜치 설정

WordPress.org 사이트의 한국어 폰트 개선을 실험하기 위한 개발 세팅입니다. – Travel in BUSAN | 부산을 여행하다

1. 개발 디렉터리 생성:
   • WSL2 터미널에서 원하는 경로에 개발 디렉터리를 만듭니다. (예: mkdir ~/dev && cd ~/dev)
   • Windows 탐색기에서도 접근하려면 /mnt/c/Users/사용자명/dev 와 같이 Windows 경로와 연결된 곳에 만드는 것이 편리합니다. 이 가이드에서는 ~/dev (WSL 홈 디렉터리 내)를 기준으로 설명합니다.
2. 관련 저장소 포크(Fork) 및 클론:
   • 먼저, GitHub에서 다음 WordPress 공식 저장소들을 자신의 계정으로 포크합니다.
     • WordPress/wporg-main-2022
     • WordPress/wporg-parent-2021
     • WordPress/wporg-mu-plugins
   • 터미널에서 포크한 저장소들을 dev 디렉터리 아래에 나란히 클론합니다.

Bash
cd ~/dev
git clone https://github.com/YOUR_GITHUB_USERNAME/wporg-main-2022.git
git clone https://github.com/YOUR_GITHUB_USERNAME/wporg-parent-2021.git
git clone https://github.com/YOUR_GITHUB_USERNAME/wporg-mu-plugins.git

1. 업스트림(Upstream) 원격 저장소 추가:
   • 각 프로젝트 디렉터리로 이동하여 WordPress 공식 저장소를 upstream으로 추가합니다. 이는 공식 저장소의 최신 변경 사항을 쉽게 가져오기 위함입니다.

cd wporg-main-2022
git remote add upstream https://github.com/WordPress/wporg-main-2022.git
cd ../wporg-parent-2021
git remote add upstream https://github.com/WordPress/wporg-parent-2021.git
cd ../wporg-mu-plugins
git remote add upstream https://github.com/WordPress/wporg-mu-plugins.git
cd ..

1. 작업 브랜치 생성 및 체크아웃:
   • 한국어 폰트 적용 작업을 위한 브랜치를 각 저장소에 생성합니다. (만약 공식 저장소에 이미 관련 작업 브랜치가 있다면, 해당 브랜치를 기반으로 생성합니다.)
   • wporg-main-2022:
     • cd wporg-main-2022
     • git fetch upstream (공식 저장소 최신 정보 가져오기)
     • git checkout -b remove/font-preloading-child upstream/remove/font-preloading-child (예시: WordPress/wporg-main-2022#560 PR 관련 브랜치, 또는 새 브랜치 git checkout -b add/korean-font upstream/trunk)
     • git push -u origin remove/font-preloading-child (자신의 포크에 브랜치 푸시)
   • wporg-parent-2021:
     • cd ../wporg-parent-2021
     • git fetch upstream
     • git checkout -b add/korean-font upstream/add/korean-font (공식 저장소에 해당 브랜치가 있다면, 없다면 upstream/trunk 기반)
     • git push -u origin add/korean-font
   • wporg-mu-plugins:
     • cd ../wporg-mu-plugins
     • git fetch upstream
     • git checkout -b add/korean-font upstream/add/korean-font (공식 저장소에 해당 브랜치가 있다면, 없다면 upstream/trunk 기반)
     • git push -u origin add/korean-font
   • cd .. (다시 ~/dev 디렉터리로)

---

3단계: wporg-main-2022 프로젝트 중심의 wp-env 환경 구성

wp-env는 wporg-main-2022 디렉터리에서만 실행하여 중앙 집중식으로 관리합니다.

1. .wp-env.override.json 파일 생성:
   • ~/dev/wporg-main-2022 디렉터리에 .wp-env.override.json 파일을 생성하고 다음 내용을 참고하여 작성합니다. (경로는 자신의 환경에 맞게 조정)

JSON
{
    "config": {
        "WP_DEBUG": true,
        "SCRIPT_DEBUG": true,
        "WP_DEBUG_LOG": true, // 또는 "/tmp/wp-errors.log" 등 WSL 경로
        "WP_DEVELOPMENT_MODE": "all",
        "WP_ENVIRONMENT_TYPE": "local",
        "JETPACK_DEV_DEBUG": true, // Jetpack 개발 모드
        "WPORG_SANDBOXED": true  // WordPress.org 샌드박스 모드
        // 기타 필요한 WordPress 상수 추가 가능
    },
    "themes": [
        // WordPress.org 기본 테마들 (wporg-main-2022의 source 디렉터리 기준)
        "./source/wp-content/themes/wporg",
        "./source/wp-content/themes/wporg-main",
        "./source/wp-content/themes/wporg-main-2022",
        // 인접 디렉터리의 wporg-parent-2021 테마 매핑
        "../wporg-parent-2021/source/wp-content/themes/wporg-parent-2021"
    ],
    "mappings": {
        // 인접 디렉터리의 wporg-mu-plugins 전체를 매핑
        "wp-content/mu-plugins/wporg-mu-plugins": "../wporg-mu-plugins",
        // 한국어 번역 파일 등 로컬 언어 파일 매핑
        "wp-content/languages": "./source/wp-content/languages",
        // wporg-main-2022 프로젝트의 기타 필요한 매핑 (선택적)
        "env": "./env",
        "wp-content/mu-plugins/0-sandbox.php": "./env/0-sandbox.php", // 주의: 위 wporg-mu-plugins 매핑과 역할 분담 명확히
        "wp-cli.yml": "./wp-cli.yml"
    }
}

1. 중요: mappings의 경로는 .wp-env.override.json 파일이 위치한 wporg-main-2022 디렉터리를 기준으로 작성합니다. ../는 상위 디렉터리를 의미합니다.

---

4단계: 의존성 설치 및 프로젝트 빌드 (WSL2 터미널)

각 프로젝트 디렉터리에서 의존성을 설치하고 빌드합니다. 브랜치를 변경하거나 원격 저장소에서 새 코드를 받아올 때마다 해당 프로젝트의 빌드 과정을 반복해야 합니다.

1. wporg-mu-plugins 빌드:

cd ~/dev/wporg-mu-plugins
composer install
yarn install
yarn build

1. wporg-parent-2021 빌드:

cd ~/dev/wporg-parent-2021
composer install
yarn install
yarn workspaces run build # 워크스페이스 사용 시, 아니면 yarn build

1. wporg-main-2022 빌드:

cd ~/dev/wporg-main-2022
composer install
yarn install
yarn workspaces run build # 워크스페이스 사용 시, 아니면 yarn build

1. 참고: composer install 후 composer.lock 파일이 변경될 수 있습니다. 이는 로컬 환경과 원본 저장소의 의존성 버전 차이 때문일 수 있습니다. 일반적으로는 composer update 패키지명 또는 composer update로 최신 호환 버전을 설치하고, 변경된 composer.lock 파일을 자신의 포크에 커밋하는 것이 좋습니다. (단, WordPress.org 기여 시에는 lockfile 변경만 있는 PR은 지양하는 분위기입니다.)

---

5단계: wp-env 실행 및 WordPress 설정

1. wp-env 실행 (WSL2 터미널 – wporg-main-2022 디렉터리에서):

cd ~/dev/wporg-main-2022
yarn wp-env stop # 이전에 실행 중이었다면 중지
yarn wp-env start --update # 변경사항 적용하며 시작

성공적으로 실행되면 Docker 컨테이너가 생성되고 로컬 WordPress 사이트가 http://localhost:8888 (기본 포트)로 실행됩니다.

1. WordPress 초기 설정 스크립트 실행 (필요시):
   • wporg-main-2022 프로젝트에 setup:tools나 setup:wp 같은 Yarn 스크립트가 있다면 실행합니다.

yarn setup:tools
yarn setup:wp

이 스크립트들은 보통 WordPress 설치, 테마 활성화, 고유 주소 설정 등을 자동화합니다.

1. 콘텐츠 가져오기 (선택적):
   • 테스트용 콘텐츠가 필요하다면, 프로젝트 내의 가져오기 스크립트를 사용합니다.

yarn wp-env run cli php env/import-content.php --url "https://wordpress.org/wp-json/wp/v2/posts?context=wporg_export&per_page=10"
yarn wp-env run cli php env/import-content.php --url "https://wordpress.org/wp-json/wp/v2/pages?context=wporg_export&per_page=10"

---

6단계: 국제화(i18n) 설정 및 테스트

1. 한국어 언어 파일 준비:
   • WordPress Polyglots 사이트에서 WordPress.org 메타 프로젝트의 한국어 번역 파일을 다운로드합니다. (예: wporg-ko_KR.mo, wporg-ko_KR.po)
   • 테마 번역 파일(wporg-main-2022-ko_KR.mo 등)도 해당 테마의 번역 프로젝트에서 다운로드합니다.
2. 언어 파일 배치:
   • ~/dev/wporg-main-2022/source/wp-content/languages/ 디렉터리에 코어 및 플러그인 언어 파일을 배치합니다.
   • ~/dev/wporg-main-2022/source/wp-content/languages/themes/ 디렉터리에 테마 언어 파일을 배치합니다.
   • .wp-env.override.json의 mappings 설정에 따라 이 경로의 파일들이 Docker 컨테이너 내의 WordPress에 반영됩니다.
3. WordPress 관리자 설정:
   • 웹 브라우저에서 http://localhost:8888/wp-admin/으로 접속합니다. (기본 ID/PW: admin/password)
   • Settings > General (설정 > 일반)에서 Site Language (사이트 언어)를 한국어로 변경합니다.
   • Dashboard > Updates (알림판 > 업데이트)에서 하단의 Update Translations (번역 업데이트) 버튼을 클릭합니다.
   • Settings > Reading (설정 > 읽기)에서 홈페이지 등을 설정합니다.
4. 폰트 적용 확인 및 테스트:
   • 사이트 프론트엔드(http://localhost:8888/)에 접속하여 제목, 본문 등에 의도한 한국어 폰트가 적용되었는지 확인합니다.
   • PHP 오류나 알림이 없는지 브라우저와 WP_DEBUG_LOG 파일 내용을 확인합니다.

---

7단계: Git 워크플로우 및 라인엔딩 설정

1. 라인엔딩 일관성 유지:
   • Windows와 WSL2를 함께 사용할 때 발생할 수 있는 줄바꿈 문자(CRLF/LF) 문제를 방지하기 위해, 각 프로젝트 루트에 .gitattributes 파일을 생성하고 다음 내용을 추가합니다. (VSCode 등 에디터에서도 기본 라인엔딩을 LF로 설정 권장)

* text=auto eol=lf
*.bat eol=crlf
# 필요한 경우 다른 Windows 특정 파일 확장자 추가

1. 일반적인 Git 작업 흐름:
   • 변경 사항이 있다면 해당 프로젝트 디렉터리에서 작업합니다.
   • git status로 변경된 파일 확인.
   • git add . 또는 git add <파일명>으로 변경 사항 스테이징.
   • git commit -m "커밋 메시지"로 로컬 저장소에 커밋.
   • git pull upstream <브랜치명>으로 공식 저장소의 최신 변경 사항을 가져와 병합(또는 리베이스). (충돌 발생 시 해결 필요)
   • git push origin <브랜치명>으로 자신의 포크 저장소에 푸시.
   • GitHub에서 공식 저장소로 Pull Request(PR) 생성.

---

문제 해결 및 팁

• PHP 오류/알림 발생 시:
  • .wp-env.override.json의 WP_DEBUG, WP_DEBUG_LOG 설정을 확인하고 로그 파일 내용을 분석합니다.
  • 관련 테마/플러그인의 빌드 과정이 올바르게 실행되었는지 확인합니다. (브랜치 변경 후에는 항상 해당 프로젝트 yarn build 실행)
  • 블록 등록 시 네임스페이스(my-plugin/my-block 형식)가 제대로 사용되었는지 코드 확인.
• composer install/update 문제:
  • composer.lock 파일과의 충돌이 의심되면, rm composer.lock 후 composer install 시도 (단, 의존성 버전이 달라질 수 있음에 유의).
  • 특정 패키지 문제 시 composer update vendor/package-name 시도.
  • wp-env 환경 실행 중에는 composer update 후 yarn wp-env restart 필요할 수 있음.
• 글로벌 헤더 등 특정 영역 폰트 미적용 시:
  • 해당 영역은 테마가 아닌 wporg-mu-plugins에서 직접 관리할 가능성이 높습니다. wporg-mu-plugins 내의 관련 코드(CSS 또는 PHP 폰트 로딩 부분)를 직접 수정하고 빌드해야 할 수 있습니다.

---

이 가이드를 통해 WordPress.org 한국어 관련 기여를 위한 안정적이고 효율적인 개발 환경을 구축하시기를 바랍니다. 궁금한 점이나 막히는 부분이 있다면 언제든지 WordPress Slack의 #meta 또는 #polyglots 채널, 또는 관련 GitHub 저장소의 Discussion을 통해 질문해주세요!