Localizeflow Docs
Korean
English Korean Japanese Chinese Spanish French
Try Localizeflow

Troubleshooting & FAQ

문제 해결 및 FAQ

Localizeflow 사용 시 자주 묻는 질문에 대한 답변을 찾고 일반적인 문제를 해결하세요.

이 페이지는 Localizeflow 사용 중 자주 발생하는 문제와 질문, 그리고 제안된 해결책을 모아놓았습니다.

처음 사용하시는 경우, 먼저 Getting started와 How Localizeflow works를 읽어보세요.

설치 및 접근 문제

조직에 GitHub 앱을 설치할 수 없습니다

GitHub 조직에서는 Localizeflow GitHub 앱 설치에 조직 소유자 권한이 필요합니다.

해결책

  • 조직 소유자에게 Install and manage the GitHub App를 따라 앱 설치를 요청하세요.
  • 설치 후 소유자는 Localizeflow 사이드바의 Teams 페이지에서 초대할 수 있습니다.

원하는 저장소가 Localizeflow에 나타나지 않습니다

+ Connect repositories 목록에 저장소가 보이지 않는 경우:

  • 앱이 해당 저장소에 GitHub에서 접근 권한을 갖고 있지 않을 수 있습니다.
  • 저장소가 앱이 설치된 계정 또는 조직과 다른 계정일 수 있습니다.

해결책

  1. GitHub에서 Localizeflow GitHub 앱 설정을 확인하세요.
  2. 다음을 확인하세요:
    • 앱이 올바른 계정 또는 조직에 설치되어 있는지.
    • 저장소가 앱의 허용 저장소 목록에 포함되어 있는지.
  3. Localizeflow로 돌아가서 + Connect repositories를 다시 시도하세요.

번역 풀 리퀘스트가 나타나지 않는 문제

자동화를 활성화했지만 풀 리퀘스트가 생성되지 않음

가능한 원인:

  • 원본 언어 파일에 관련 변경사항이 없음
  • 포함/제외 경로가 파일과 일치하지 않음
  • 자동화가 일시 중지되었거나 비활성화됨

해결책

  1. 번역 설정에 예상하는 폴더들이 포함되어 있는지 확인하세요 (예: docs/en/**, blog/en/**, **/*.md).
  2. 저장소에 대해 자동화가 활성화되어 있는지 확인하세요.
  3. 원본 파일에 작은 테스트 수정사항을 만들고 지정된 브랜치에 푸시하세요.
  4. 잠시 기다린 후 번역 풀 리퀘스트가 생성되는지 확인하세요.

일부 파일만 번역되고 있음

특정 파일이 번역 풀 리퀘스트에 포함되지 않을 경우:

  • 설정에 의해 제외되었을 수 있음
  • 경로가 포함 패턴과 일치하지 않을 수 있음

해결책

  • 포함 및 제외 패턴을 다시 검토하세요.
  • 원하는 파일이 명시적으로 포함 패턴에 포함되고 실수로 제외되지 않았는지 확인하세요.

정적 문서 문제

정적 문서 프로젝트에 이미 번역된 폴더가 있음 (예: docs/ko)

기존 번역 폴더가 있으면 Localizeflow가 이를 추가 소스 콘텐츠로 인식할 수 있습니다. 이로 인해 번역이 중복되거나 혼란스러운 차이가 발생할 수 있습니다.

해결책

  1. 자동화 활성화 전에 오래되었거나 수동으로 관리되는 번역 폴더를 제거하세요:
    • docs/ko, docs/ja
    • blog/ko, blog/ja
    • i18n/* 또는 유사한 출력 폴더
  2. 원본 콘텐츠를 언어별 소스 폴더로 이동하세요. 예:
    • docs/en/**
    • blog/en/**
  3. 번역 설정을 업데이트하여 새 소스 경로를 포함시키세요.

자세한 내용은 Static documentation sites를 참고하세요.

권한 및 협업

팀원이 Localizeflow에서 프로젝트를 볼 수 없음

팀원이 예상대로 저장소나 설정을 보지 못하는 경우:

  • 팀원이 올바른 Localizeflow 작업공간에 초대받지 못했을 수 있음
  • GitHub 저장소에 대한 접근 권한이 없을 수 있음

해결책

  1. Localizeflow의 Teams 페이지에서 해당 팀원이 작업공간 멤버인지 확인하세요.
  2. 아니면 이메일로 초대하거나 초대 링크를 공유하세요.
  3. 관련 GitHub 저장소에 대해 적절한 권한이 있는지 확인하세요.

일반 질문

번역을 일시 중지할 수 있나요?

네. 대규모 구조 변경을 하거나 잡음을 줄이고 싶을 때 저장소에 대한 자동화를 비활성화하거나 일시 중지할 수 있습니다. 자동화를 일시 중지하면 Localizeflow는 다시 활성화될 때까지 새 번역 풀 리퀘스트를 생성하지 않습니다.

번역을 수동으로 편집하면 어떻게 되나요?

번역된 파일은 언제든지 직접 편집할 수 있습니다. 변경 사항이 병합되면 저장소 히스토리에 포함됩니다. Localizeflow는 번역을 현재 소스 콘텐츠와 맞추는 데 집중하며 임의로 사용자의 변경사항을 덮어쓰지 않습니다.

배포나 CI/CD 설정을 변경해야 하나요?

대부분의 경우 변경할 필요 없습니다. Localizeflow는 GitHub 브랜치와 풀 리퀘스트를 통해 작동합니다. CI/CD 파이프라인이 저장소 콘텐츠를 기반으로 빌드한다면, 번역 풀 리퀘스트 병합 후 Localizeflow가 생성한 번역 파일이 자동으로 포함됩니다.

Localizeflow가 프런트매터를 어떻게 처리하나요?

Localizeflow는 Markdown 파일의 프런트매터 필드를 지능적으로 처리합니다:

  • 번역하는 필드: title, description, excerpt 등 사용자에게 보이는 텍스트
  • 보존하는 필드: slug, id, date, author, tags, order, section 등 기술적 필드
  • 경로 조정: image, cover, og_image 같은 이미지 경로는 번역된 파일 위치에 맞게 자동으로 업데이트됨

예시:

원본 파일 (docs/en/getting-started.md):

---
title: Getting Started
description: Learn how to get started with our platform
slug: getting-started
section: introduction
order: 1
sidebar_position: 1
image: ../images/hero.png
date: 2024-01-15
author: john-doe
tags: [tutorial, beginner]
---

번역 파일 (docs/ko/getting-started.md):

---
title: 시작하기                                    # ← Translated
description: 우리 플랫폼 시작 방법 알아보기           # ← Translated
slug: getting-started                            # ← Preserved
section: introduction                            # ← Preserved
order: 1                                         # ← Preserved
sidebar_position: 1                              # ← Preserved
image: ../images/hero.png                        # ← Preserved (same depth)
date: 2024-01-15                                # ← Preserved
author: john-doe                                # ← Preserved
tags: [tutorial, beginner]                      # ← Preserved
---


경로 조정은 번역 파일 깊이가 원본 파일과 다를 때만 발생합니다. 예를 들어, 원본이 docs/getting-started.md이고 번역이 translations/ko/docs/getting-started.md라면 상대 경로가 그에 맞게 조정됩니다.

이 과정은 자동으로 이루어지므로 별도 설정이 필요 없습니다.

특정 필드에 대한 맞춤 프런트매터 처리가 필요하면 문의해 주세요. 프로젝트에 맞게 설정해 드립니다.