# NAME

App::Greple::xlate - Greple용 번역 지원 모듈

# SYNOPSIS

    greple -Mxlate --xlate-engine gpt5 --xlate pattern target-file

    greple -Mxlate --xlate-engine deepl --xlate pattern target-file

# VERSION

Version 2.01

# DESCRIPTION

**Greple** **xlate** 모듈은 원하는 텍스트 블록을 찾아 번역된 텍스트로 대체합니다. 주 엔진은 GPT-5.5 (`llm/gpt5.pm`)이며, 이 엔진은 [llm](https://llm.datasette.io/) 명령을 호출합니다. DeepL (`deepl.pm`) 및 기존 **gpty** 기반 엔진도 포함되어 있습니다.

번역 결과는 파일별로 캐시되므로, 변경되지 않은 텍스트에 대해서는 명령을 다시 실행해도 비용이 발생하지 않습니다. 문서가 편집되면 변경된 단락만 API로 다시 전송됩니다. 문맥 인식 엔진은 변경된 부분 주변의 번역문, 변경 전 원본 텍스트, 그리고 편집된 단락의 이전 버전도 함께 수신하므로, 새로운 번역은 기존 표현 방식을 유지합니다(**--xlate-context-window** 참조). 민감한 문자열은 전송 전에 숨길 수 있습니다(["ANONYMIZATION AND TEMPLATES"](#anonymization-and-templates) 참조).

Perl의 pod 스타일로 작성된 문서의 일반 텍스트 블록을 번역하려면, 다음과 같이 **greple** 명령을 `--xlate-engine gpt5` 및 `perl` 모듈과 함께 사용하십시오:

    greple -Mxlate --xlate-engine gpt5 -Mperl --pod --re '^([\w\pP].*\n)+' --all foo.pm

이 명령에서 패턴 문자열 `^([\w\pP].*\n)+`은 영숫자 및 구두점으로 시작하는 연속된 줄을 의미합니다. 이 명령은 번역할 영역을 강조 표시합니다. 옵션 **--all**은 전체 텍스트를 생성하는 데 사용됩니다.

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/select-area.png">
    </p>
</div>

그런 다음 `--xlate` 옵션을 추가하여 선택한 영역을 번역합니다. 그러면 원하는 섹션을 찾아 번역 엔진의 출력 결과로 대체합니다.

기본적으로 원본 및 번역된 텍스트는 [git(1)](http://man.he.net/man1/git)과 호환되는 "충돌 마커" 형식으로 인쇄됩니다. `ifdef` 형식을 사용하면 [unifdef(1)](http://man.he.net/man1/unifdef) 명령으로 원하는 부분을 쉽게 얻을 수 있습니다. 출력 형식은 **--xlate-format** 옵션으로 지정할 수 있습니다.

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/format-conflict.png">
    </p>
</div>

전체 텍스트를 번역하려면 **--match-all** 옵션을 사용합니다. 이는 전체 텍스트와 일치하는 `(?s).+` 패턴을 지정하는 단축키입니다.

충돌 마커 형식 데이터는 [sdif](https://metacpan.org/pod/App%3A%3Asdif) 명령과 `-V` 옵션을 사용하여 나란히 나란히 볼 수 있습니다. 문자열 단위로 비교하는 것은 의미가 없으므로 `--no-cdif` 옵션을 사용하는 것이 좋습니다. 텍스트에 색상을 지정할 필요가 없는 경우 `--no-textcolor`(또는 `--no-tc`)를 지정합니다.

    sdif -V --no-filename --no-tc --no-cdif data_shishin.deepl-EN-US.cm

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/sdif-cm-view.png">
    </p>
</div>

# NORMALIZATION

처리는 지정된 단위로 수행되지만 비어 있지 않은 여러 줄의 텍스트 시퀀스의 경우 한 줄로 함께 변환됩니다. 이 작업은 다음과 같이 수행됩니다:

- 각 줄의 시작과 끝에서 공백을 제거합니다.
- 한 줄이 전폭 구두점 문자로 끝나면 다음 줄로 연결합니다.
- 한 줄이 전폭 문자로 끝나고 다음 줄이 전폭 문자로 시작되는 경우 두 줄을 연결합니다.
- 한 줄의 끝이나 시작이 전폭 문자가 아닌 경우 공백 문자를 삽입하여 연결합니다.

캐시 데이터는 정규화된 텍스트를 기반으로 관리되므로 정규화 결과에 영향을 미치지 않는 수정이 이루어지더라도 캐시된 번역 데이터는 여전히 유효합니다.

이 정규화 프로세스는 첫 번째(0번째) 및 짝수 패턴에 대해서만 수행됩니다. 따라서 다음과 같이 두 개의 패턴을 지정하면 첫 번째 패턴과 일치하는 텍스트는 정규화 후 처리되고 두 번째 패턴과 일치하는 텍스트에는 정규화 프로세스가 수행되지 않습니다.

    greple -Mxlate -E normalized -E not-normalized

따라서 여러 줄을 한 줄로 결합하여 처리할 텍스트에는 첫 번째 패턴을 사용하고, 미리 서식이 지정된 텍스트에는 두 번째 패턴을 사용합니다. 첫 번째 패턴에 일치할 텍스트가 없는 경우 `(?!)`과 같이 아무것도 일치하지 않는 패턴을 사용합니다.

# MASKING

간혹 번역하고 싶지 않은 텍스트 부분이 있을 수 있습니다. 예를 들어 마크다운 파일의 태그가 있습니다. DeepL 에서는 이러한 경우 제외할 텍스트 부분을 XML 태그로 변환하여 번역한 다음 번역이 완료된 후 복원할 것을 제안합니다. 이를 지원하기 위해 번역에서 마스킹할 부분을 지정할 수 있습니다.

    --xlate-setopt maskfile=MASKPATTERN

이것은 파일 `MASKPATTERN`의 각 줄을 정규 표현식으로 해석하고, 일치하는 문자열을 번역한 후 처리 후 원상태로 복원합니다. `#`로 시작하는 줄은 무시됩니다.

복잡한 패턴은 백슬래시로 이스케이프 처리된 줄바꿈을 사용하여 여러 줄에 걸쳐 작성할 수 있습니다.

마스킹을 통해 텍스트가 어떻게 변환되는지는 **--xlate-mask** 옵션에서 확인할 수 있습니다.

마스킹은 마크업이 번역되는 것을 방지합니다. 번역 서비스 자체에서 민감한 문자열을 숨기려면 ["ANONYMIZATION AND TEMPLATES"](#anonymization-and-templates)을 참조하십시오. 두 방법을 함께 사용할 수도 있습니다.

이 인터페이스는 실험적이며 향후 변경될 수 있습니다.

# ANONYMIZATION AND TEMPLATES

민감한 문자열은 번역 API로 전송되기 전에 숨길 수 있으며, 출력 시 복원할 수 있습니다. 익명화 규칙은 사전 파일(**--xlate-anonymize**), 문서 내 인라인 마크(**--xlate-anonymize-mark**), YAML 프론트매터 값(**--xlate-frontmatter**)의 세 가지 출처에서 제공됩니다. 각 문자열은 전송 중에 `<person id=1 />`와 같은 범주 태그로 대체됩니다. 숨김 처리는 API 전송 시에만 적용되며, 로컬 캐시 파일에는 복원된 일반 텍스트가 저장됩니다. 정확히 어떤 내용이 전송될지 확인하려면 **--xlate-dryrun**를 사용하십시오.

양식 문서(분기 보고서 등)의 경우, 관련 주체를 미리 정의하고 본문에서 이를 참조하십시오:

    ---
    報告者: 山田太郎
    発注会社: アクメ株式会社
    ---
    本件について {{ 報告者 }} が調査を行った。

`--xlate-template`를 사용하여 언어별로 템플릿을 한 번씩 번역한 후 (값이 파일에 저장되는 경우 `--xlate-frontmatter`을 사용), 그런 다음 **pandoc-embedz** 독립 모드로 각 사례를 렌더링합니다. 외부 구성 파일의 `global:` 아래에 있는 값은 번역 API에 전혀 전달되지 않습니다:

    greple -Mxlate --xlate --xlate-engine=gpt5 --xlate-to=EN-US \
           --xlate-template= --xlate-format=xtxt \
           --match-paragraph --all --need=0 \
           report-template.md > report-template.EN.md
    pandoc-embedz --standalone report-template.EN.md \
                  -c case-123.yaml -o report-123.EN.md < /dev/null

인라인 마크의 경우, 매크로 정의 구성을 제공하면 동일한 번역된 템플릿이 실제 이름이나 편집된 버전을 렌더링합니다:

    # macros.yaml           # macros-redacted.yaml
    preamble: |             preamble: |
      {% macro person(name) %}{{ name }}{% endmacro %}
                              {% macro person(name) %}(関係者){% endmacro %}

문서에 embedz 블록이 포함된 경우 번역에서 이를 제외합니다:

    --exclude '^```embedz\n(?s:.*?)^```\n'

# OPTIONS

- **--xlate**
- **--xlate-color**
- **--xlate-fold**
- **--xlate-fold-width**=_n_ (Default: 70)

    일치하는 각 영역에 대해 번역 프로세스를 호출합니다.

    이 옵션이 없으면 **greple**은 일반 검색 명령처럼 작동합니다. 따라서 실제 작업을 호출하기 전에 파일에서 어느 부분이 번역 대상이 될지 확인할 수 있습니다.

    명령 결과는 표준 아웃으로 이동하므로 필요한 경우 파일로 리디렉션하거나 [App::Greple::update](https://metacpan.org/pod/App%3A%3AGreple%3A%3Aupdate) 모듈을 사용하는 것을 고려할 수 있습니다.

    옵션 **--xlate**는 **--color=never** 옵션과 함께 **--xlate-color** 옵션을 호출합니다.

    **--xlate-fold** 옵션을 사용하면 변환된 텍스트가 지정된 너비만큼 접힙니다. 기본 너비는 70이며 **--xlate-fold-width** 옵션으로 설정할 수 있습니다. 실행 작업을 위해 4개의 열이 예약되어 있으므로 각 줄에는 최대 74자가 들어갈 수 있습니다.

- **--xlate-engine**=_engine_

    사용할 번역 엔진을 지정합니다.

    현재 사용 가능한 엔진은 다음과 같습니다.

    - **gpt5**: gpt-5.5 (via the `llm` command)
    - **deepl**: DeepL API (via the `deepl` command)
    - **gpt3**: gpt-3.5-turbo (legacy, via the `gpty` command)
    - **gpt4o**: gpt-4o-mini (legacy, via the `gpty` command)

    엔진 모듈은 먼저 백엔드 네임스페이스(`llm`, 그 다음 `gpty`)에서 검색된 후, `App::Greple::xlate` 바로 아래에서 검색됩니다. 따라서 `gpt5`은 `App::Greple::xlate::llm::gpt5`을 로드하고, 이는 `llm` 명령을 호출하는 반면, `gpt4o`은 `App::Greple::xlate::gpty::gpt4o`으로 대체됩니다. 특정 백엔드를 강제 적용하려면 `--xlate-setopt backend=gpty`을 사용하십시오.

- **--xlate-labor**
- **--xlabor**

    번역 엔진을 호출하는 대신 작업해야 합니다. 번역할 텍스트를 준비한 후 클립보드에 복사합니다. 양식에 붙여넣고 결과를 클립보드에 복사한 다음 Return 키를 누르면 됩니다.

- **--xlate-to** (Default: `EN-US`)

    대상 언어를 지정하십시오. LLM 엔진은 모델이 이해하는 모든 언어 이름이나 코드를 허용하며, 이는 번역 프롬프트에 삽입됩니다. **DeepL** 엔진을 사용할 때 `deepl languages` 명령어를 통해 사용 가능한 언어를 확인할 수 있습니다.

- **--xlate-from** (Default: `ORIGINAL`)

    `conflict`, `colon` 및 `ifdef` 출력 형식에서 원본 텍스트에 사용되는 레이블입니다. **DeepL** 엔진을 사용할 경우, 기본값이 아닌 값도 소스 언어로 전달됩니다.

- **--xlate-format**=_format_ (Default: `conflict`)

    원본 및 번역 텍스트의 출력 형식을 지정합니다.

    `xtxt` 이외의 다음 형식은 번역할 부분이 줄의 모음이라고 가정합니다. 실제로는 한 줄의 일부만 번역할 수 있지만 `xtxt` 이외의 형식을 지정하면 의미 있는 결과가 나오지 않습니다.

    - **conflict**, **cm**

        원본 텍스트와 변환된 텍스트는 [git(1)](http://man.he.net/man1/git) 충돌 마커 형식으로 인쇄됩니다.

            <<<<<<< ORIGINAL
            original text
            =======
            translated Japanese text
            >>>>>>> JA

        다음 [sed(1)](http://man.he.net/man1/sed) 명령으로 원본 파일을 복구할 수 있습니다.

            sed -e '/^<<<<<<< /d' -e '/^=======$/,/^>>>>>>> /d'

    - **colon**, _:::::::_

        원본 텍스트와 번역된 텍스트는 마크다운의 사용자 정의 컨테이너 스타일로 출력됩니다.

            ::::::: ORIGINAL
            original text
            :::::::
            ::::::: JA
            translated Japanese text
            :::::::

        위의 텍스트는 HTML에서 다음과 같이 번역됩니다.

            <div class="ORIGINAL">
            original text
            </div>
            <div class="JA">
            translated Japanese text
            </div>

        콜론 개수는 기본적으로 7입니다. `:::::`와 같이 콜론 순서를 지정하면 콜론 7개 대신 사용됩니다.

    - **ifdef**

        원본 텍스트와 변환된 텍스트는 [cpp(1)](http://man.he.net/man1/cpp) `#ifdef` 형식으로 인쇄됩니다.

            #ifdef ORIGINAL
            original text
            #endif
            #ifdef JA
            translated Japanese text
            #endif

        일본어 텍스트만 검색하려면 **unifdef** 명령으로 검색할 수 있습니다:

            unifdef -UORIGINAL -DJA foo.ja.pm

    - **space**
    - **space+**

        원본 텍스트와 변환된 텍스트는 하나의 빈 줄로 구분하여 인쇄됩니다. `스페이스+`의 경우 변환된 텍스트 뒤에 줄 바꿈도 출력합니다.

    - **xtxt**

        형식이 `xtxt`(번역된 텍스트) 또는 알 수 없는 경우 번역된 텍스트만 인쇄됩니다.

- **--xlate-maxlen**=_chars_ (Default: 0)

    API에 한 번에 전송할 텍스트의 최대 길이를 지정합니다. 기본값 0은 엔진 자체의 제한을 의미합니다. 무료 DeepL 계정 서비스의 경우 API(**--xlate**)는 128K, 클립보드 인터페이스(**--xlate-labor**)는 5000입니다. Pro 서비스를 이용 중이라면 이 값을 변경할 수 있습니다.

- **--xlate-maxline**=_n_ (Default: 0)

    한 번에 API로 전송할 텍스트의 최대 줄 수를 지정합니다.

    한 번에 한 줄씩 번역하려면 이 값을 1로 설정합니다. 이 옵션은 `--xlate-maxlen` 옵션보다 우선합니다.

- **--xlate-prompt**=_text_

    번역 엔진에 전송할 사용자 지정 프롬프트를 지정합니다. 이 옵션은 LLM 엔진(`gpt3`, `gpt4o`, `gpt5`)에서 사용할 수 있지만 DeepL에서는 사용할 수 없습니다. AI 모델에 구체적인 지침을 제공하여 번역 동작을 사용자 지정할 수 있습니다. 프롬프트에 `%s`이 포함되어 있으면 대상 언어 이름으로 대체됩니다.

- **--xlate-context**=_text_

    번역 엔진에 전송할 추가 컨텍스트 정보를 지정합니다. 이 옵션을 여러 번 사용하여 여러 개의 컨텍스트 문자열을 제공할 수 있습니다. 컨텍스트 정보는 번역 엔진이 배경을 이해하고 보다 정확한 번역을 생성하는 데 도움이 됩니다.

- **--xlate-context-window**=_n_

    (Context-aware engines only, e.g. `gpt5` on the llm backend)
    변경된 블록을 재번역할 때 참조 컨텍스트로 전달되는 주변 번역 블록의 수(기본값 2). 이 컨텍스트에는 변경된 영역 주변의 원본 텍스트(제목, 목록 구조, 캡션)와, 가능한 경우 캐시에서 복원된 변경된 텍스트의 이전 버전도 포함되어 변경되지 않은 문구가 보존됩니다. 컨텍스트 기반 번역을 완전히 비활성화하려면 0으로 설정하십시오. 각 변경된 영역은 별도의 API 호출로 번역되며, 컨텍스트로 인해 시스템 프롬프트에 최대 약 8000자까지 추가될 수 있으므로, 컨텍스트 기반 번역은 일관성을 위해 약간의 추가 비용을 감수해야 합니다.

- **--xlate-cache-seed**=_file_

    다른 문서의 캐시 파일을 사용하여 새 문서의 캐시를 초기화합니다. 정기 보고서에 유용합니다. 새 호의 캐시에 이전 호의 캐시를 초기값으로 설정하면, 변경되지 않은 단락은 다시 번역되지 않고, 편집된 단락은 이전 호의 문구를 유지합니다. 시드는 대상 캐시가 비어 있을 때만 사용되며, 그렇지 않은 경우 경고와 함께 무시됩니다. 기본값인 `--xlate-cache=auto`의 경우, 시드를 지정하면 새 문서의 캐시 파일도 생성됩니다.

- **--xlate-anonymize**=_file_

    민감한 문자열을 번역 API로 전송하기 전에 익명화하고, 출력 시 원본을 복원합니다. 사전 파일은 항목당 하나의 항목을 제공하며, JSON 형식(표준, 기계 생성 가능)

        [ { "category": "person",  "text": "山田太郎" },
          { "category": "company", "regex": "アクメ(株式会社)?" } ]

    또는 간단한 줄 형식(정규 표현식의 경우 `category pattern`, `/.../`)으로 제공됩니다. 각 항목은 `<person id=1 />`과 같은 카테고리 태그로 대체됩니다. 동일한 문자열에는 항상 동일한 태그가 부여되므로, 모델이 각 항목의 정체성을 추적할 수 있습니다. 알 수 없는 JSON 필드는 무시되므로, 생성기(예: 엔티티를 추출하는 로컬 LLM)는 자체 주석을 추가할 수 있습니다. 카테고리 `lit`는 예약되어 있습니다. 로컬 캐시 파일에는 여전히 복원된 일반 텍스트가 저장되며, 은닉 대상은 API 전송 시에만 적용됩니다.

    사전(dictionary)은 외부 도구(예: 민감한 엔티티를 추출하는 로컬 모델)를 통해 생성될 수 있습니다:

        llm -m <local-model> \
            -s 'Extract sensitive entities as a JSON array of objects
                with "category" and "text" fields.' \
            < report.md > report.anon.json
        greple -Mxlate --xlate-anonymize=report.anon.json ...

    파일 내의 UTF-8 BOM은 허용됩니다. 프론트 매터(front matter) 라인 형식의 값은 해당 줄 끝에만 주석을 달 수 있으며, 값 뒤에는 주석을 달 수 없습니다.

- **--xlate-anonymize-mark**\[=_regex_\]

    문서 자체의 인라인 마크에서 익명화 항목을 수집합니다. 첫 번째 출현을 `{{ person("山田太郎") }}`와 같이 표시하면 문서 전체에서 해당 문자열이 나타나는 모든 위치가 익명화됩니다. 마크 자체는 원본과 번역본에 그대로 남아 있으므로, 문서는 Jinja2 스타일의 매크로 프로세서로도 처리할 수 있습니다(이름을 출력하거나 가리기 위해 `person` 매크로를 정의하십시오). 사용자 정의 _regex_에는 `(?<category>...)` 및 `(?<text>...)`이라는 이름의 캡처가 포함되어야 합니다.

    이와 같이 값이 선택적인 옵션의 경우, 뒤따르는 파일 인수가 값으로 간주된다는 점에 유의하십시오. 기본 표기법을 사용할 때는 `--xlate-anonymize-mark=`(뒤에 `=`가 붙은 형태)를 작성하십시오.

    대체 표기법을 구성할 수 있습니다. 예를 들어, `@@person:NAME@@` 스타일의 마크에 대해 `--xlate-anonymize-mark='@@(?<category>[a-z][a-z0-9_]*):(?<text>[^\n]+?)@@'`을 사용하거나, 렌더링된 마크다운에서 보이지 않는 HTML 주석 형식을 사용할 수 있습니다. 마크 규칙은 문서별로 수집됩니다. 즉, 한 입력 파일에서 마크된 문자열은 동일한 실행의 다른 파일에서는 숨겨지지 않습니다(파일 간에 누적되는 프론트 매터 값과는 달리).

- **--xlate-template**\[=_regex_\]

    템플릿 표현식(기본값: Jinja2 `{{ ... }}`, `{% ... %}`, `{# ... #}`)을 불투명한 자리 표시자로 취급합니다. 모델에 이를 변경 없이 복사하도록 지시하고, 블록별로 응답에 정확히 동일한 표현식이 각각 동일한 횟수만큼 포함되어 있는지 확인합니다. 번역 과정에서 대상 언어의 어순에 맞춰 순서가 재조정될 수 있으므로, 표현식의 순서는 달라질 수 있습니다. 표현식이 손상된 경우 실행이 중단되며, 캐시는 체크포인트로 저장되고 고정되므로 비용을 지불한 내용은 손실되지 않습니다.

    이와 같은 선택적 값 옵션의 경우, 뒤따르는 파일 인수가 값으로 간주된다는 점에 유의하십시오: 기본 표기법을 사용할 때는 `--xlate-template=` (뒤에 `=`가 붙은 형태)를 작성하십시오.

- **--xlate-frontmatter**

    선두에 있는 `---` ... `---` 블록을 YAML 프론트 매터로 취급합니다: 번역 및 2단계 컨텍스트 슬라이스에서 이를 제외하고, 안전 장치로서 해당 블록의 평면 `key: value` 값을 익명화 규칙(카테고리 `var`)에 추가합니다. 입력 파일이 여러 개인 경우 수집된 값은 누적됩니다(은닉을 우선시함).

    닫는 태그 `---` 뒤에는 항상 빈 줄을 남겨야 합니다. 단락 스타일의 일치 패턴을 사용할 경우, 본문 텍스트와 바로 이어지는 프론트 매터는 하나의 걸쳐 있는 블록을 형성하며, 이 블록은 제외 규칙으로 억제할 수 없습니다(이 경우 경고가 출력됨); 값은 여전히 익명화되지만, 프론트 매터 자체는 번역 요청 대상으로 전송됩니다.

- **--xlate-glossary**=_glossary_

    번역에 사용할 용어집 ID를 지정합니다. 이 옵션은 DeepL 엔진을 사용할 때만 사용할 수 있습니다. 용어집 ID는 DeepL 계정에서 가져와야 하며 특정 용어의 일관된 번역을 보장합니다.

- **--xlate-dryrun**

    번역 API를 호출하지 말고, 대신 진행 상황 표시를 통해 각 페이로드를 (익명화 및 마스킹 후) 전송될 그대로 정확히 보여주십시오. 이는 시스템에서 어떤 데이터가 전송되는지 확인하고 실행 비용을 추정하는 데 유용합니다.

- **--**\[**no-**\]**xlate-progress** (Default: True)

    STDERR 출력에서 번역 결과를 실시간으로 확인할 수 있습니다. `From` 페이로드는 익명화 및 마스킹 처리 후 전송되는 그대로 표시됩니다.

- **--xlate-stripe**

    일치하는 부분을 지브라 스트라이프 방식으로 표시하려면 [App::Greple::stripe](https://metacpan.org/pod/App%3A%3AGreple%3A%3Astripe) 모듈을 사용합니다. 이 옵션은 일치하는 부분이 연속적으로 연결될 때 유용합니다.

    색상 팔레트는 단말기의 배경색에 따라 전환됩니다. 명시적으로 지정하고 싶으면 **--지연 스트라이프-밝음** 또는 **--지연 스트라이프-어두움**을 사용할 수 있습니다.

- **--xlate-mask**

    마스킹 기능을 수행하여 변환된 텍스트를 복원하지 않고 그대로 표시합니다.

- **--match-all**

    파일의 전체 텍스트를 대상 영역으로 설정합니다.

- **--lineify-cm**
- **--lineify-colon**

    `cm` 및 `colon` 형식의 경우 출력이 한 줄씩 분할되어 형식이 지정됩니다. 따라서 한 줄의 일부만 번역해야 하는 경우 예상되는 결과를 얻을 수 없습니다. 이 필터는 한 줄의 일부를 정상적인 줄 단위 출력으로 번역하여 손상된 출력을 수정합니다.

    현재 구현에서는 한 줄의 여러 부분이 번역되는 경우 독립된 줄로 출력됩니다.

# CACHE OPTIONS

**엑스레이트** 모듈은 각 파일에 대한 번역 텍스트를 캐시하여 저장하고 실행 전에 읽어들여 서버에 요청하는 오버헤드를 없앨 수 있습니다. 기본 캐시 전략 `auto`를 사용하면 대상 파일에 대한 캐시 파일이 존재할 때만 캐시 데이터를 유지합니다.

캐시 관리를 시작하거나 기존의 모든 캐시 데이터를 정리하려면 **--xlate-cache=clear**를 사용합니다. 이 옵션을 실행하면 캐시 파일이 없는 경우 새 캐시 파일이 생성되고 이후 자동으로 유지 관리됩니다.

- --xlate-cache=_strategy_
    - `auto` (Default)

        캐시 파일이 있는 경우 캐시 파일을 유지 관리합니다.

    - `create`

        빈 캐시 파일을 생성하고 종료합니다.

    - `always`, `yes`, `1`

        타겟이 정상 파일인 한 캐시를 유지합니다.

    - `clear`

        캐시 데이터를 먼저 지웁니다.

    - `never`, `no`, `0`

        캐시 파일이 존재하더라도 절대 사용하지 않습니다.

    - `accumulate`

        기본 동작에 따라 사용하지 않는 데이터는 캐시 파일에서 제거됩니다. 제거하지 않고 파일에 유지하려면 `accumulate`를 사용하세요.
- **--xlate-update**

    이 옵션은 필요하지 않은 경우에도 캐시 파일을 강제로 업데이트합니다.

# COMMAND LINE INTERFACE

이 모듈은 배포에 포함된 `xlate` 명령을 사용하여 명령줄에서 쉽게 사용할 수 있습니다. 사용법은 `xlate` 매뉴얼 페이지를 참조하세요.

`xlate` 명령은 `--to-lang`, `--from-lang`, `--engine` 및 `--file`와 같은 GNU 스타일의 긴 옵션을 지원합니다. 사용 가능한 모든 옵션을 보려면 `xlate -h`을 사용하세요.

`xlate` 명령은 Docker 환경과 함께 작동하므로 아무것도 설치되어 있지 않더라도 Docker를 사용할 수 있으면 사용할 수 있습니다. `-D` 또는 `-C` 옵션을 사용합니다.

Docker 작업은 [App::dozo](https://metacpan.org/pod/App%3A%3Adozo)으로 처리되며, 독립 실행형 명령으로도 사용할 수 있습니다. `dozo` 명령은 영구 컨테이너 설정을 위한 `.dozorc` 구성 파일을 지원합니다.

또한 다양한 문서 스타일에 대한 메이크파일이 제공되므로 특별한 지정 없이 다른 언어로 번역이 가능합니다. `-M` 옵션을 사용합니다.

Docker와 `make` 옵션을 결합하여 `make`를 Docker 환경에서 실행할 수도 있습니다.

`xlate -C`처럼 실행하면 현재 작업 중인 git 리포지토리가 마운트된 셸이 시작됩니다.

자세한 내용은 ["또는 참조"](#또는-참조) 섹션의 일본어 기사를 참조하세요.

# EMACS

저장소에 포함된 `xlate.el` 파일을 로드하여 Emacs 편집기에서 `xlate` 명령을 사용합니다. `xlate-region` 함수는 지정된 지역을 번역합니다. 기본 언어는 `EN-US`이며 접두사 인수를 사용하여 호출하는 언어를 지정할 수 있습니다.

<div>
    <p>
    <img width="750" src="https://raw.githubusercontent.com/kaz-utashiro/App-Greple-xlate/main/images/emacs.png">
    </p>
</div>

# ENVIRONMENT

- DEEPL\_AUTH\_KEY

    DeepL 서비스에 대한 인증 키를 설정합니다.

- OPENAI\_API\_KEY

    레거시 **gpty** 엔진에서 사용하는 OpenAI 인증 키입니다. `llm` 기반 **gpt5** 엔진도 이 변수를 읽지만, `llm keys set openai`에 저장된 키도 작동합니다.

- GREPLE\_XLATE\_CACHE

    기본 캐시 전략을 설정합니다(["CACHE OPTIONS"](#cache-options) 참조).

# INSTALL

## CPANMINUS

    $ cpanm App::Greple::xlate

## TOOLS

사용 중인 엔진에 맞는 명령줄 도구를 설치하세요: `llm`는 **gpt5** 엔진용, `deepl`는 DeepL용, `gpty`는 레거시 GPT 엔진용입니다.

[https://llm.datasette.io/](https://llm.datasette.io/)

[https://github.com/DeepLcom/deepl-python](https://github.com/DeepLcom/deepl-python)

[https://github.com/tecolicom/App-gpty](https://github.com/tecolicom/App-gpty)

# SEE ALSO

## MODULES

[App::Greple::xlate::llm](https://metacpan.org/pod/App%3A%3AGreple%3A%3Axlate%3A%3Allm), [App::Greple::xlate::deepl](https://metacpan.org/pod/App%3A%3AGreple%3A%3Axlate%3A%3Adeepl)

[App::dozo](https://metacpan.org/pod/App%3A%3Adozo) - xlate에서 컨테이너 작업에 사용하는 일반 Docker 러너입니다.

## RELATED MODULES

- [App::Greple](https://metacpan.org/pod/App%3A%3AGreple)

    대상 텍스트 패턴에 대한 자세한 내용은 **greple** 매뉴얼을 참조하세요. **--내부**, **--외부**, **--포함**, **--제외** 옵션을 사용하여 일치하는 영역을 제한할 수 있습니다.

- [App::Greple::update](https://metacpan.org/pod/App%3A%3AGreple%3A%3Aupdate)

    `-Mupdate` 모듈을 사용하여 **greple** 명령의 결과에 따라 파일을 수정할 수 있습니다.

- [App::sdif](https://metacpan.org/pod/App%3A%3Asdif)

    충돌 마커 형식을 **-V** 옵션과 함께 나란히 표시하려면 **에스디프**를 사용합니다.

- [App::Greple::stripe](https://metacpan.org/pod/App%3A%3AGreple%3A%3Astripe)

    회색 **줄무늬** 모듈은 **--xlate-stripe** 옵션으로 사용합니다.

## RESOURCES

- [https://hub.docker.com/r/tecolicom/xlate](https://hub.docker.com/r/tecolicom/xlate)

    도커 컨테이너 이미지.

- [https://github.com/tecolicom/getoptlong](https://github.com/tecolicom/getoptlong)

    `getoptlong.sh` - `xlate` 스크립트 및 [App::dozo](https://metacpan.org/pod/App%3A%3Adozo)에서 옵션 구문 분석에 사용되는 라이브러리.

- [https://llm.datasette.io/](https://llm.datasette.io/)

    **gpt5** 엔진이 LLM 모델에 접근하기 위해 사용하는 `llm` 명령어입니다.

- [https://github.com/DeepLcom/deepl-python](https://github.com/DeepLcom/deepl-python)

    DeepL 파이썬 라이브러리 및 CLI 명령.

- [https://github.com/openai/openai-python](https://github.com/openai/openai-python)

    OpenAI 파이썬 라이브러리

- [https://github.com/tecolicom/App-gpty](https://github.com/tecolicom/App-gpty)

    OpenAI 명령줄 인터페이스

## ARTICLES

- [https://qiita.com/kaz-utashiro/items/1c1a51a4591922e18250](https://qiita.com/kaz-utashiro/items/1c1a51a4591922e18250)

    필요한 부분만 번역하고 DeepL API(일본어)로 대체하는 Greple 모듈 (일본어)

- [https://qiita.com/kaz-utashiro/items/a5e19736416ca183ecf6](https://qiita.com/kaz-utashiro/items/a5e19736416ca183ecf6)

    DeepL API 모듈로 15개 언어로 문서 생성 (일본어)

- [https://qiita.com/kaz-utashiro/items/1b9e155d6ae0620ab4dd](https://qiita.com/kaz-utashiro/items/1b9e155d6ae0620ab4dd)

    DeepL API를 사용한 자동 번역 도커 환경 (일본어)

# AUTHOR

Kazumasa Utashiro

# LICENSE

Copyright © 2023-2026 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
