자주 묻는 질문 (FAQ)¶

일반¶

오프라인 환경에서도 사용할 수 있나요?¶

네, 대부분 가능합니다. 세부적인 지원 범위는 다음과 같습니다:

번역: LLM이 필요합니다. 기본 제공되는 무료 Gemini API는 온라인 환경에서 작동하지만, Custom Provider 설정을 통해 로컬 Ollama / LM Studio를 연결하면 완전 오프라인 번역이 가능합니다.
OCR: Tesseract 또는 EasyOCR을 사용하면 오프라인에서 작동합니다.
STT (음성 인식): Whisper(기본값)를 사용하면 오프라인에서 작동합니다.
TTS (음성 합성): 기본 엔진인 Edge TTS, 그리고 ElevenLabs / Google Cloud TTS / Gemini TTS는 온라인 환경(무료 또는 유료)에서 작동합니다. 반면 Piper TTS는 완전 오프라인 신경망 TTS 모델입니다. 설정 → 음성 → Piper TTS → 지금 음성 다운로드 메뉴에서 언어별 음성 파일(약 25–60MB ONNX 파일)을 한 번 다운로드해 두면, 이후로는 API 키나 네트워크 연결 없이 사용할 수 있습니다.

※ 완전한 외부망 차단(Air-gapped) 환경에서는 다음 설정을 조합하세요: 로컬 LLM(Custom Provider), Tesseract/EasyOCR, Whisper, Piper TTS.

번역된 파일은 어디에 저장되나요?¶

기본적으로 원본 파일과 동일한 위치에 _translated_<원본언어>_<대상언어> 접미사가 붙어 저장됩니다(예: report_translated_en_fr.docx). 저장 위치는 설정 → 일반 → 번역 저장 경로 메뉴에서 기능별로 변경할 수 있습니다.

설정 파일은 어디에 보관되나요?¶

운영체제별 INI 파일 경로는 다음과 같습니다:

OS	경로
Linux	`~/.config/ai-translate/settings.ini`
macOS	`~/Library/Preferences/ai-translate/settings.ini`
Windows	`%APPDATA%\ai-translate\settings.ini`

API 키는 OS 키체인에 안전하게 저장되며 INI 파일에는 기록되지 않습니다. 번역 히스토리는 데이터 디렉터리 내부의 SQLite 데이터베이스(DB)에 저장됩니다.

내 데이터(문서, 음성 등)는 어떻게 처리되나요?¶

로컬 처리 우선: 사용자가 클라우드 기반 LLM / OCR / STT / TTS 서비스를 명시적으로 호출하지 않는 한, 모든 데이터는 컴퓨터 외부로 전송되지 않습니다.
사용자 추적(Telemetry) 없음: 이 앱은 사용자 데이터를 수집하거나 외부 서버로 전송하지 않습니다. 앱에서 발생하는 유일한 외부 네트워크 요청은 GitHub 릴리스를 확인하는 선택적 업데이트 알림 기능뿐이며, 이마저도 설정 → 일반에서 끌 수 있습니다. 물론 클라우드 기반 번역/음성 인식 기능을 사용할 때는 해당 서비스를 제공하는 벤더(Google, ElevenLabs 등) 서버와 통신합니다.
API 키 보안: 입력한 API 키는 운영체제의 암호화된 키체인에 저장됩니다. (단, 헤드리스 리눅스 서버처럼 OS 키체인을 사용할 수 없는 환경에서는 예외적으로 INI 파일에 일반 텍스트로 저장됩니다.)

Google 문서 / Notion 페이지를 번역할 수 있나요?¶

문서를 직접 번역하는 기능은 지원하지 않습니다. 해당 플랫폼에서 문서를 .docx, Markdown, HTML 등으로 먼저 내보낸(Export) 뒤 AI Translate로 번역하고, 번역된 파일을 플랫폼에 다시 가져오기(Import)를 수행해야 합니다.

모델 및 엔진 선택 가이드¶

어떤 LLM 모델을 선택하는 것이 좋은가요?¶

사용 목적에 따라 다음을 권장합니다:

Gemini Flash 모델: 무료로 사용할 수 있고 속도가 매우 빠르며 번역 품질도 훌륭합니다. 일상적인 번역에 적합합니다. (예: gemini-2.5-flash, gemini-3.0-flash 등)
Gemini Pro 모델: 종량제(Pay-as-you-go)로 운영되지만, 번역 품질이 가장 높습니다. 법률 문서, 기술 문서, 고객에게 제공할 중요한 문서에 적합합니다.
로컬 Ollama (7B~13B 모델): 오프라인 환경이나 데이터 프라이버시가 매우 중요할 때 선택하세요.

앱 내 기능별로 다른 모델을 지정할 수 있으므로, 간단한 텍스트 번역에는 빠른 모델을 사용하고 중요한 문서 번역에는 고성능(유료) 모델을 사용하도록 각각 설정할 수 있습니다.

어떤 OCR 엔진을 사용해야 하나요?¶

Tesseract: 가장 대중적이며 깨끗하게 인쇄된 텍스트 추출에 적합합니다. 무료이고 오프라인에서 빠르게 작동합니다.
EasyOCR: 라틴 알파벳이 아닌 문자(특히 한중일 한자 및 CJK 스크립트)나 화질이 떨어지는 노이즈 이미지에 강합니다.
Google Cloud Vision: 손글씨, 다양한 언어가 섞인 문서, 그리고 가장 높은 정확도가 필요할 때 추천합니다. (클라우드 서비스, 유료)

어떤 STT(음성 인식) 엔진을 사용해야 하나요?¶

오프라인 환경 및 프라이버시 보호가 중요할 땐 Whisper local.
다수의 화자가 대화하는 오디오 녹음에는 Soniox (발화자별 자막(SRT) 구분 지원).
전화 통화나 의료 관련 오디오처럼 특정 도메인에 특화된 음성에는 Google Cloud STT.
실시간 음성 대화 번역에는 Gemini Live.

어떤 TTS(음성 합성) 엔진을 선택해야 하나요?¶

무료이면서도 뛰어난 품질의 음성이 필요할 땐 Edge TTS.
최고 품질의 프리미엄 음성이나 특정 브랜드를 위한 음성 클로닝에는 ElevenLabs.
Edge TTS에서 지원하지 않는 소수 사용 언어(Long-tail)의 고품질 음성이 필요할 땐 Google Cloud TTS.
설정해 둔 Gemini API 키를 재사용해 무료로 자연스러운 음성을 생성하려면 Gemini TTS.
완전 오프라인 환경에서 음성을 출력하려면 Piper TTS. 단, 각 언어의 음성 파일(약 25~60MB)을 최초 1회 다운로드해야 하며, 앱이 지원하는 45개 언어 중 13개 언어는 아직 Piper 음성이 제공되지 않습니다. (지원하지 않는 언어를 요청할 경우 자동으로 Edge TTS로 대체되어 작동합니다.)

워크플로우¶

전체 폴더를 어떻게 번역하나요?¶

문서 번역 화면의 드래그 앤 드롭 영역에 전체 폴더를 끌어다 놓으세요. 폴더 내부에 있는 모든 지원 가능한 파일(하위 폴더 포함)이 작업 대기열에 추가됩니다. 지원하지 않는 파일은 알아서 무시됩니다. 단, 한 번에 최대 100개의 파일만 끌어다 놓을 수 있으므로 대규모 작업은 여러 번에 나누어 진행하세요.

번역을 일시 중지하고 재개할 수 있나요?¶

네, 가능합니다. 작업 도중 언제든지 앱을 종료하셔도 됩니다. 대기 중(Pending)이거나 번역 중(Translating)이던 작업은 다음 번 앱 실행 시 이어서 진행됩니다. 내부적으로 체크포인트 기능이 작동하므로, 예를 들어 100페이지 PDF 문서를 번역하다 47페이지에서 멈췄다면 다음 번에 48페이지부터 바로 이어서 번역합니다.

번역을 수동으로 편집할 수 있나요?¶

텍스트 번역 기능: 번역 결과가 표시되는 오른쪽 패널을 클릭해 직접 텍스트를 수정할 수 있습니다. 수정된 내용은 해당 번역 기록(History)에 자동으로 저장됩니다.
문서 번역 기능: 번역이 완료된 파일을 평소 사용하시는 문서 편집기(Word, LibreOffice 등)로 열어서 내용을 수정하시면 됩니다. 단, 외부 편집기에서 수정한 내용은 AI Translate 앱 내부의 번역 히스토리에 반영되지 않습니다.

코드 문자열이나 단어 목록을 한 번에 일괄 번역할 수 있나요?¶

CLI 명령어(ait)를 활용할 수 있습니다:

ait *.txt --target French

혹은 내부 프로세스의 문자열(예: 코드에서 추출한 UI 텍스트 배열)을 번역해야 할 때는 MCP translate_text 도구에 목록을 넘기거나 파이썬(Python) API를 직접 호출할 수도 있습니다:

from src.core.llm_engine import translate_text
out = translate_text(texts=["Hello", "World"], target_lang="French")

용어집(Glossary) 기능¶

LLM이 제가 등록한 용어집을 무시하고 번역하는 것 같습니다.¶

다음 세 가지를 확인해 보세요:

용어집 세트가 활성화(체크 표시)되어 있는지 확인하세요.
원본 텍스트에 용어집에 등록된 원본 단어가 정확히 존재하는지 확인하세요. (API 토큰을 절약하기 위해 원본 텍스트에 등장하는 용어만 추려 LLM에 전달합니다. 따라서 원본 용어집에 오타가 있다면 매칭되지 않아 LLM에 전달되지 않습니다.)
너무 가벼운 모델을 사용 중인지 확인하세요. flash-lite와 같은 경량 모델은 종종 용어집 힌트를 무시하는 경향이 있습니다. flash나 pro 모델을 사용하면 훨씬 잘 준수합니다.

용어집 단어 매칭 시 대소문자나 악센트를 구분하나요?¶

구분하지 않습니다. 용어집 내부 매칭 로직과 앱 내 검색창 모두 악센트 기호를 무시하고 대소문자를 동일하게 취급하는 정규화(Normalization) 처리를 거칩니다. 따라서 용어집에 원본 단어를 Café라고 등록해두면 문장 내에서 cafe, CAFE로 쓰이더라도 모두 정상적으로 매칭됩니다.

보안 및 개인정보 보호¶

앱 사용 기록이나 번역 데이터를 수집하나요?¶

전혀 수집하지 않습니다. 앱 내부에는 사용자 활동을 추적하는 Analytics SDK가 존재하지 않습니다. 앱 실행 시 새 버전 확인을 위해 GitHub Releases 페이지에 한 번 접근하는 것이 전부이며, 이 기능조차 설정 → 일반 메뉴에서 완전히 끌 수 있습니다.

제가 입력한 API 키는 안전하게 보관되나요?¶

네, 안전합니다. 운영체제(OS)가 제공하는 암호화된 키체인 시스템(macOS Keychain, Windows Credential Manager, Linux Secret Service)에 저장됩니다. 따라서 다른 프로그램이 명시적 허가 없이 키를 빼갈 수 없습니다.

단, OS 키체인 데몬을 사용할 수 없는 환경(예: 디스플레이가 없는 헤드리스 리눅스 서버 등)에 한해서는 사용자 설정 폴더 내의 INI 파일에 일반 텍스트로 보관됩니다. 이 경우 암호화되진 않지만, 파일 시스템 권한(File Permission)을 통해 다른 시스템 사용자가 열어볼 수 없도록 보호됩니다.