문제 해결 및 FAQ

이 페이지는 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는 frontmatter를 어떻게 처리하나요?

Localizeflow는 Markdown 파일의 frontmatter 필드를 지능적으로 처리합니다:

• 번역: 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
---

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

특정 필드에 대해 맞춤 frontmatter 처리가 필요하면 문의해 주세요. 프로젝트에 맞게 구성해 드립니다.

다음 단계

• Getting started – 첫 번째 번역으로 빠르게 가는 길.
• Static documentation sites – Astro, Hugo, Docusaurus 등 유사 프로젝트를 위한 안내.