WordPress에서 번역이 표시되지 않는 이유 (문제 해결 가이드)

WordPress 개발에서 "침묵의 실패"만큼 답답한 것은 없습니다.

모든 것을 올바르게 수행했습니다. .po 파일을 번역했습니다. .mo 파일로 컴파일했습니다. FTP를 통해 서버에 업로드했습니다. 캐시를 지웠습니다.

페이지를 새로 고쳐 스페인어, 프랑스어 또는 독일어를 볼 수 있기를 기대합니다. 대신 영어만 표시됩니다.

오류 메시지도, 흰색 화면도 없이 그저 고집스럽게 번역되지 않은 텍스트만 보입니다. 머리카락을 쥐어뜯기 전에 이 가이드를 읽어보세요. WordPress에서 번역이 로드되지 않는 5가지 가장 일반적인 이유와 해결 방법은 다음과 같습니다.

1. 파일 이름을 잘못 지정했습니다.

WordPress는 파일 이름 지정에 매우 엄격합니다. 문자 하나라도 놓치면 파일이 로드되지 않습니다.

표준 형식은 {text-domain}-{locale}.mo입니다.

• 텍스트 도메인: 테마 또는 플러그인의 고유 ID입니다 (예: woocommerce, twentytwentyfour, my-custom-plugin).
• 로케일: WP 로케일 코드입니다 (예: 스페인어 스페인의 경우 es_ES, 프랑스어의 경우 fr_FR).

일반적인 실수:

• 파일 이름을 es_ES.mo로만 지정하는 경우 (플러그인이 아닌 전역 WordPress 코어 파일에만 해당됩니다).
• 잘못된 대시를 사용하는 경우: my_plugin_es_ES.mo (밑줄) 대신 my-plugin-es_ES.mo (하이픈).
• 텍스트 도메인을 추측하는 경우. 플러그인의 코드를 확인하여 정확한 슬러그를 찾아야 합니다 (style.css 헤더 또는 load_plugin_textdomain 함수).

2. 파일을 잘못된 폴더에 넣었습니다.

파일을 업로드하는 위치는 파일 이름만큼 중요합니다. WordPress는 특정 디렉토리를 특정 순서로 찾습니다.

• "안전한" 시스템 폴더: /wp-content/languages/plugins/ 또는 /wp-content/languages/themes/.
  • 장점: 플러그인 업데이트로부터 안전합니다.
  • 단점: 파일 이름을 textdomain-locale.mo로 지정해야 합니다.
• 작성자 폴더: /wp-content/plugins/plugin-name/languages/.
  • 장점: 찾기 쉽습니다.
  • 단점: 위험. 플러그인을 업데이트하면 이 폴더가 완전히 지워집니다. 번역이 사라집니다.

가장 좋은 방법: 업데이트 중에 데이터 손실을 방지하려면 사용자 정의 .mo 파일을 항상 전역 /wp-content/languages/ 디렉토리에 넣으세요.

3. "조용한 살인자": .po 파일의 손상된 구문

이 문제는 디버깅하기 가장 어렵고 일반적인 AI 번역 도구에서 자주 발생합니다.

WordPress는 .po 텍스트 파일에서 컴파일된 바이너리 .mo 파일을 읽습니다. .po 파일에 구문 오류가 있으면 .mo 파일이 생성될 수 있지만 내부적으로 "손상"됩니다.

이것은 어떻게 발생합니까? 번역가 (사람 또는 AI)가 Gettext 형식을 망치면 문자열이 유효하지 않게 됩니다.

• 예: 닫는 따옴표 "가 누락되었습니다.
• 예: 변수를 깨뜨리는 경우 (%s를 % s로 변경).
• 예: msgid_plural 개수를 엉망으로 만드는 경우.

WordPress가 .mo 파일에서 손상된 항목을 발견하면 건너뛰거나 파일 읽기를 완전히 중단하여 원래 영어로 되돌아가는 경우가 많습니다.

4. 컴파일하는 것을 잊었습니다 (.po vs .mo)

WordPress는 .po 파일을 직접 읽을 수 없습니다. 이는 일반적인 오해입니다.

• .po = 사람이 읽을 수 있음 (Portable Object).
• .mo = 기계가 읽을 수 있음 (Machine Object).

my-theme-es_ES.po 파일을 업로드했지만 일치하는 .mo 파일 생성을 잊어버린 경우 아무 일도 일어나지 않습니다. 컴파일해야 합니다.

5. 캐싱 (일반적인 용의자)

캐싱 플러그인 (WP Rocket, LiteSpeed) 또는 서버 측 캐싱 (Varnish, Redis)을 사용하는 경우 사이트에서 번역을 업로드하기 전의 캐시된 HTML 버전을 제공하고 있을 수 있습니다.

해결 방법: 브라우저 캐시 및 객체 캐시를 포함한 모든 캐시를 지우세요.

궁극적인 해결 방법: 처음부터 유효한 파일

파일 경로 및 이름 문제 해결은 쉽습니다. 손상된 구문 (이유 #3) 문제 해결은 악몽입니다.

코드 변수를 깨거나 Gettext 구조를 손상시키는 도구를 사용하는 경우 파일 자체가 "중독"된 것을 깨닫지 못하고 파일이 작동하지 않는 이유를 궁금해하며 몇 시간을 보낼 것입니다.

이것이 바로 SimplePoTranslate를 구축한 이유입니다.

• 구문 잠금: 다운로드하기 전에 모든 문자열이 구문적으로 유효한지 확인합니다. %s와 같은 변수를 잠가 깨지지 않도록 합니다.
• 완벽한 서식: 작동하는 .mo 파일로 100% 컴파일되는 깨끗하고 표준적인 .po 파일을 생성합니다.
• 플러그인 불필요: 파일을 다운로드하면 작동한다는 것을 알 수 있습니다. 올바른 폴더에 업로드하기만 하면 됩니다.
• WordPress 플러그인: 수동 업로드를 완전히 건너뛰고 싶으신가요? 공식 SimplePoTranslate WordPress 플러그인은 테마 및 플러그인 .pot 파일을 자동으로 감지하고 클라우드에서 번역한 다음 올바른 파일 이름으로 올바른 디렉토리에 결과를 배포합니다. 더 이상 잘못된 파일 이름, 잘못된 폴더 경로 — 번역이 나타나지 않는 가장 일반적인 두 가지 이유가 없습니다.

번역이 보이지 않는 이유를 추측하지 마세요. 신뢰할 수 있는 파일로 시작하세요.

골치 아픈 일 없이 번역할 준비가 되셨나요? SimplePoTranslate.com에서 무료로 시작하세요.