=encoding utf-8

=head1 NAME

App::Greple::xlate - modul dukungan penerjemahan untuk greple

=head1 SYNOPSIS

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

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

=head1 VERSION

Version 2.01

=head1 DESCRIPTION

B<Greple> B<xlate> modul akan menemukan blok teks yang diinginkan dan menggantinya dengan teks terjemahan. Mesin utama yang digunakan adalah GPT-5.5 (F<llm/gpt5.pm>), yang memanggil perintah L<llm|https://llm.datasette.io/>; DeepL (F<deepl.pm>) dan mesin berbasis B<gpty> yang sudah ada sebelumnya juga disertakan.

Terjemahan disimpan dalam cache per berkas, sehingga menjalankan kembali perintah tidak memerlukan biaya tambahan untuk teks yang tidak berubah. Saat dokumen diedit, hanya paragraf yang berubah yang dikirim kembali ke API; mesin yang peka konteks juga menerima terjemahan di sekitarnya, teks sumber mentah di sekitar perubahan, dan versi sebelumnya dari paragraf yang diedit, sehingga terjemahan baru tetap mempertahankan gaya penulisan yang sudah ada (lihat B<--xlate-context-window>). String yang sensitif dapat disembunyikan sebelum dikirim (lihat L</ANONYMIZATION AND TEMPLATES>).

Jika Anda ingin menerjemahkan blok teks biasa dalam dokumen yang ditulis dalam gaya pod Perl, gunakan perintah B<greple> bersama modul C<--xlate-engine gpt5> dan C<perl> seperti ini:

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

Dalam perintah ini, string pola C<^([\w\pP].*\n)+> berarti baris berurutan yang dimulai dengan alfanumerik dan tanda baca. Perintah ini menunjukkan area yang akan diterjemahkan dengan disorot. Opsi B<--all> digunakan untuk menghasilkan seluruh teks.

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

Kemudian tambahkan opsi C<--xlate> untuk menerjemahkan area yang dipilih. Selanjutnya, sistem akan menemukan bagian-bagian yang diinginkan dan menggantinya dengan hasil terjemahan dari mesin terjemahan.

Secara default, teks asli dan terjemahan dicetak dalam format "penanda konflik" yang kompatibel dengan L<git(1)>. Dengan menggunakan format C<ifdef>, Anda dapat memperoleh bagian yang diinginkan dengan perintah L<unifdef(1)> dengan mudah. Format keluaran dapat ditentukan dengan opsi B<--xlate-format>.

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

Jika Anda ingin menerjemahkan seluruh teks, gunakan opsi B<--match-all>. Ini adalah jalan pintas untuk menentukan pola C<(?s).+> yang cocok dengan seluruh teks.

Data format penanda konflik dapat dilihat dalam gaya berdampingan dengan perintah L<sdif|App::sdif> dengan opsi C<-V>. Karena tidak masuk akal untuk membandingkan per string, opsi C<--no-cdif> direkomendasikan. Jika Anda tidak perlu mewarnai teks, tentukan C<--no-textcolor> (atau C<--no-tc>).

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

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

=head1 NORMALIZATION

Pemrosesan dilakukan dalam unit yang ditentukan, tetapi dalam kasus urutan beberapa baris teks yang tidak kosong, teks-teks tersebut dikonversi bersama menjadi satu baris. Operasi ini dilakukan sebagai berikut:

=over 2

=item *

Menghilangkan spasi pada awal dan akhir setiap baris.

=item *

Jika sebuah baris diakhiri dengan karakter tanda baca dengan lebar penuh, gabungkan dengan baris berikutnya.

=item *

Jika sebuah baris diakhiri dengan karakter dengan lebar penuh dan baris berikutnya dimulai dengan karakter dengan lebar penuh, gabungkan kedua baris tersebut.

=item *

Jika akhir atau awal baris bukan merupakan karakter dengan lebar penuh, gabungkan keduanya dengan menyisipkan karakter spasi.

=back

Data cache dikelola berdasarkan teks yang dinormalisasi, sehingga meskipun ada modifikasi yang dilakukan yang tidak memengaruhi hasil normalisasi, data terjemahan yang ditembolok akan tetap efektif.

Proses normalisasi ini dilakukan hanya untuk pola pertama (ke-0) dan pola bernomor genap. Dengan demikian, jika dua pola ditentukan sebagai berikut, teks yang cocok dengan pola pertama akan diproses setelah normalisasi, dan tidak ada proses normalisasi yang dilakukan pada teks yang cocok dengan pola kedua.

    greple -Mxlate -E normalized -E not-normalized

Oleh karena itu, gunakan pola pertama untuk teks yang akan diproses dengan menggabungkan beberapa baris menjadi satu baris, dan gunakan pola kedua untuk teks yang telah diformat sebelumnya. Jika tidak ada teks yang cocok dengan pola pertama, gunakan pola yang tidak cocok dengan apa pun, seperti C<(?!)>.

=head1 MASKING

Terkadang, ada bagian teks yang tidak ingin diterjemahkan. Misalnya, tag dalam file penurunan harga. DeepL menyarankan agar dalam kasus seperti itu, bagian teks yang akan dikecualikan dikonversi ke tag XML, diterjemahkan, dan kemudian dikembalikan setelah terjemahan selesai. Untuk mendukung hal ini, dimungkinkan untuk menentukan bagian yang akan disembunyikan dari terjemahan.

    --xlate-setopt maskfile=MASKPATTERN

Ini akan menginterpretasikan setiap baris berkas C<MASKPATTERN> sebagai ekspresi reguler, menerjemahkan string yang cocok dengannya, dan mengembalikan setelah diproses. Baris yang dimulai dengan C<#> diabaikan.

Pola yang kompleks dapat ditulis dalam beberapa baris dengan baris baru yang di-escape menggunakan tanda garis miring terbalik.

Bagaimana teks diubah dengan masking dapat dilihat dengan opsi B<--xlate-mask>.

Penyamaran melindungi markup agar tidak diterjemahkan. Untuk menyembunyikan string sensitif dari layanan terjemahan itu sendiri, lihat L</ANONYMIZATION AND TEMPLATES>; keduanya dapat digunakan bersamaan.

Antarmuka ini bersifat eksperimental dan dapat berubah di masa depan.

=head1 ANONYMIZATION AND TEMPLATES

String sensitif dapat disembunyikan sebelum dikirim ke API terjemahan dan dipulihkan dalam hasil terjemahan. Tersedia tiga sumber aturan anonimisasi: berkas kamus (B<--xlate-anonymize>), tanda inline dalam dokumen itu sendiri (B<--xlate-anonymize-mark>), dan nilai front matter YAML (B<--xlate-frontmatter>). Setiap string diganti dengan tag kategori seperti C<< <person id=1 /> >> selama transmisi. Sasaran penyembunyian hanya pada transmisi API: berkas cache lokal menyimpan teks biasa yang telah dipulihkan. Gunakan B<--xlate-dryrun> untuk memeriksa dengan tepat apa yang akan dikirimkan.

Untuk dokumen formulir (laporan triwulanan dan sejenisnya), tentukan aktor di bagian awal dan rujuk mereka di bagian isi:

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

Terjemahkan templat sekali per bahasa dengan C<--xlate-template> (dan C<--xlate-frontmatter> jika nilainya disimpan dalam berkas), lalu tampilkan setiap kasus dengan mode mandiri B<pandoc-embedz> — nilai di bawah C<global:> dalam konfigurasi eksternal sama sekali tidak sampai ke API terjemahan:

    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

Untuk tanda-tanda inline, menyediakan konfigurasi definisi makro akan membuat templat terjemahan yang sama menampilkan nama asli atau versi yang disunting:

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

Kecualikan blok embedz dari terjemahan jika dokumen mengandungnya:

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

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

=item B<--xlate-fold-width>=I<n> (Default: 70)

Memanggil proses penerjemahan untuk setiap area yang cocok.

Tanpa opsi ini, B<greple> berperilaku sebagai perintah pencarian biasa. Jadi, Anda dapat memeriksa bagian mana dari file yang akan menjadi subjek terjemahan sebelum memanggil pekerjaan yang sebenarnya.

Hasil perintah akan keluar ke standar, jadi alihkan ke file jika perlu, atau pertimbangkan untuk menggunakan modul L<App::Greple::update>.

Opsi B<--xlate> memanggil opsi B<--xlate-color> dengan opsi B<--color=never>.

Dengan opsi B<--xlate-fold>, teks yang dikonversi akan dilipat dengan lebar yang ditentukan. Lebar default adalah 70 dan dapat diatur dengan opsi B<--xlate-fold-width>. Empat kolom dicadangkan untuk operasi run-in, sehingga setiap baris dapat menampung paling banyak 74 karakter.

=item B<--xlate-engine>=I<engine>

Menentukan mesin terjemahan yang akan digunakan.

Pada saat ini, mesin berikut ini tersedia

=over 2

=item * B<gpt5>: gpt-5.5 (via the C<llm> command)

=item * B<deepl>: DeepL API (via the C<deepl> command)

=item * B<gpt3>: gpt-3.5-turbo (legacy, via the C<gpty> command)

=item * B<gpt4o>: gpt-4o-mini (legacy, via the C<gpty> command)

=back

Modul mesin dicari terlebih dahulu di ruang nama backend (C<llm>, lalu C<gpty>), kemudian langsung di bawah C<App::Greple::xlate>. Jadi, C<gpt5> memuat C<App::Greple::xlate::llm::gpt5> yang memanggil perintah C<llm>, sedangkan C<gpt4o> menggunakan C<App::Greple::xlate::gpty::gpt4o> sebagai cadangan. Gunakan C<--xlate-setopt backend=gpty> untuk memaksa penggunaan backend tertentu.

=item B<--xlate-labor>

=item B<--xlabor>

Alih-alih memanggil mesin penerjemah, Anda diharapkan untuk bekerja. Setelah menyiapkan teks yang akan diterjemahkan, teks tersebut disalin ke clipboard. Anda diharapkan untuk menempelkannya ke formulir, menyalin hasilnya ke clipboard, dan menekan return.

=item B<--xlate-to> (Default: C<EN-US>)

Tentukan bahasa target. Mesin LLM menerima nama atau kode bahasa apa pun yang dipahami model; hal ini akan disisipkan ke dalam prompt terjemahan. Anda dapat melihat bahasa yang tersedia melalui perintah C<deepl languages> saat menggunakan mesin B<DeepL>.

=item B<--xlate-from> (Default: C<ORIGINAL>)

Label yang digunakan untuk teks asli dalam format keluaran C<conflict>, C<colon>, dan C<ifdef>. Dengan mesin B<DeepL>, nilai non-default juga diteruskan sebagai bahasa sumber.

=item B<--xlate-format>=I<format> (Default: C<conflict>)

Tentukan format output untuk teks asli dan terjemahan.

Format berikut ini selain C<xtxt> mengasumsikan bahwa bagian yang akan diterjemahkan adalah kumpulan baris. Pada kenyataannya, dimungkinkan untuk menerjemahkan hanya sebagian dari sebuah baris, tetapi menentukan format selain C<xtxt> tidak akan menghasilkan hasil yang berarti.

=over 4

=item B<conflict>, B<cm>

Teks asli dan teks yang dikonversi dicetak dalam format penanda konflik L<git(1)>.

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

Anda dapat memulihkan file asli dengan perintah L<sed(1)> berikutnya.

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

=item B<colon>, I<:::::::>

Teks asli dan terjemahan ditampilkan dalam gaya wadah khusus penurunan harga.

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

Teks di atas akan diterjemahkan ke dalam HTML berikut ini.

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

Jumlah titik dua adalah 7 secara default. Jika Anda menentukan urutan titik dua seperti C<:::::>, ini digunakan sebagai pengganti 7 titik dua.

=item B<ifdef>

Teks asli dan teks yang dikonversi dicetak dalam format L<cpp(1)> C<#ifdef>.

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

Anda hanya dapat mengambil teks bahasa Jepang dengan perintah B<unifdef>:

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Teks asli dan teks yang dikonversi dicetak dipisahkan oleh satu baris kosong. Untuk C<spasi+>, ini juga menghasilkan baris baru setelah teks yang dikonversi.

=item B<xtxt>

Jika formatnya adalah C<xtxt> (teks terjemahan) atau tidak diketahui, hanya teks terjemahan yang dicetak.

=back

=item B<--xlate-maxlen>=I<chars> (Default: 0)

Tentukan panjang maksimum teks yang akan dikirim ke API sekaligus. Nilai default 0 berarti batas yang ditetapkan oleh mesin itu sendiri: untuk layanan akun DeepL gratis, batasnya adalah 128K untuk API (B<--xlate>) dan 5000 untuk antarmuka clipboard (B<--xlate-labor>). Anda mungkin dapat mengubah nilai-nilai ini jika menggunakan layanan Pro.

=item B<--xlate-maxline>=I<n> (Default: 0)

Tentukan jumlah maksimum baris teks yang akan dikirim ke API sekaligus.

Tetapkan nilai ini ke 1 jika Anda ingin menerjemahkan satu baris dalam satu waktu. Opsi ini lebih diutamakan daripada opsi C<--xlate-maxlen>.

=item B<--xlate-prompt>=I<text>

Tentukan prompt khusus yang akan dikirim ke mesin terjemahan. Opsi ini tersedia untuk mesin LLM (C<gpt3>, C<gpt4o>, C<gpt5>) tetapi tidak untuk DeepL. Anda dapat menyesuaikan perilaku terjemahan dengan memberikan instruksi spesifik kepada model AI. Jika prompt berisi C<%s>, maka akan diganti dengan nama bahasa target.

=item B<--xlate-context>=I<text>

Tentukan informasi konteks tambahan yang akan dikirim ke mesin penerjemahan. Opsi ini dapat digunakan beberapa kali untuk memberikan beberapa string konteks. Informasi konteks membantu mesin penerjemah memahami latar belakang dan menghasilkan terjemahan yang lebih akurat.

=item B<--xlate-context-window>=I<n>

(Context-aware engines only, e.g. C<gpt5> on the llm backend)
Jumlah blok terjemahan di sekitarnya yang diteruskan sebagai konteks referensi saat menerjemahkan ulang blok yang diubah (default 2). Konteks ini juga mencakup teks sumber mentah di sekitar wilayah yang diubah (judul, struktur daftar, keterangan) dan, jika tersedia, versi sebelumnya dari teks yang diubah yang diambil dari cache, sehingga kata-kata yang tidak diubah tetap dipertahankan. Atur ke 0 untuk menonaktifkan terjemahan berbasis konteks sepenuhnya. Perhatikan bahwa setiap wilayah yang diubah diterjemahkan dalam panggilan API tersendiri dan konteks dapat menambah hingga sekitar 8.000 karakter ke prompt sistem, sehingga terjemahan berbasis konteks menukar biaya tambahan dengan konsistensi.

=item B<--xlate-cache-seed>=I<file>

Menginisialisasi cache dokumen baru dari berkas cache dokumen lain. Berguna untuk laporan berkala: menginisialisasi cache edisi baru dengan cache edisi sebelumnya, sehingga paragraf yang tidak diubah tidak diterjemahkan ulang dan paragraf yang diedit mempertahankan redaksi edisi sebelumnya. Benih hanya digunakan jika cache tujuan kosong; jika tidak, benih tersebut diabaikan dengan peringatan. Dengan pengaturan default C<--xlate-cache=auto>, menentukan benih juga berarti membuat berkas cache dokumen baru.

=item B<--xlate-anonymize>=I<file>

Anonimkan string sensitif sebelum dikirim ke API terjemahan, dan pulihkan kembali dalam hasil keluaran. Berkas kamus memberikan satu entri per item: dalam format JSON (kanonik, dapat dihasilkan oleh mesin)

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

atau dalam format baris sederhana (C<category pattern>, C</.../> untuk regex). Setiap item diganti dengan tag kategori seperti C<< <person id=1 /> >>; string yang sama selalu mendapatkan tag yang sama, sehingga model dapat melacak identitas masing-masing. Bidang JSON yang tidak dikenal diabaikan, sehingga generator (misalnya LLM lokal yang mengekstrak entitas) dapat menambahkan anotasi mereka sendiri. Kategori C<lit> dicadangkan. File cache lokal tetap menyimpan teks biasa yang dipulihkan: penyembunyian hanya ditujukan untuk transmisi API.

Kamus dapat dihasilkan oleh alat eksternal — misalnya model lokal yang mengekstrak entitas sensitif:

    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 ...

BOM UTF-8 dalam berkas ditoleransi. Nilai dalam format baris front matter hanya boleh disertai komentar penutup pada barisnya sendiri, bukan setelah nilai tersebut.

=item B<--xlate-anonymize-mark>[=I<regex>]

Kumpulkan entri anonimisasi dari tanda-tanda inline di dalam dokumen itu sendiri. Tandai kemunculan pertama seperti C<{{ person("山田太郎") }}> dan setiap kemunculan string tersebut di seluruh dokumen akan dianonimkan. Tanda itu sendiri tetap ada di sumber dan di terjemahan, sehingga dokumen juga dapat diproses oleh pemroses makro bergaya Jinja2 (tentukan makro C<person> untuk mencetak atau menyunting nama tersebut). Sebuah I<regex> kustom harus berisi penangkapan bernama C<< (?<category>...) >> dan C<< (?<text>...) >>.

Perhatikan bahwa dengan opsi nilai opsional seperti ini, argumen file berikutnya akan dianggap sebagai nilainya: tulis C<--xlate-anonymize-mark=> (dengan C<=> di bagian akhir) saat menggunakan notasi default.

Notasi alternatif dapat dikonfigurasi, misalnya C<< --xlate-anonymize-mark='@@(?<category>[a-z][a-z0-9_]*):(?<text>[^\n]+?)@@' >> untuk tanda bergaya C<@@person:NAME@@>, atau bentuk komentar HTML yang tetap tidak terlihat dalam Markdown yang dirender. Aturan penandaan dikumpulkan per dokumen: string yang ditandai dalam satu berkas masukan tidak disembunyikan dalam berkas lain pada proses yang sama (berbeda dengan nilai front matter, yang terakumulasi di seluruh berkas).

=item B<--xlate-template>[=I<regex>]

Perlakukan ekspresi templat (default: Jinja2 C<{{ ... }}>, C<{% ... %}>, C<{# ... #}>) sebagai penanda tempat yang tidak transparan: instruksikan model untuk menyalinnya tanpa perubahan dan verifikasi, per blok, bahwa respons berisi ekspresi yang persis sama, masing-masing dengan jumlah kemunculan yang sama. Urutannya mungkin berubah, karena terjemahan secara sah mengubah urutannya agar mengikuti urutan kata dalam bahasa sasaran. Ekspresi yang rusak akan menghentikan proses; cache akan dicatat dan dibekukan, sehingga tidak ada yang terbuang dari hasil yang telah dibayar.

Perhatikan bahwa dengan opsi nilai opsional seperti ini, argumen berkas yang mengikuti akan dianggap sebagai nilainya: tulis C<--xlate-template=> (dengan C<=> di bagian akhir) saat menggunakan notasi default.

=item B<--xlate-frontmatter>

Perlakukan blok C<---> ... C<---> sebagai bagian awal YAML: kecualikan dari terjemahan dan dari potongan konteks fase-2, serta tambahkan nilai C<key: value> datarnya ke aturan anonimisasi (kategori C<var>) sebagai jaring pengaman. Jika ada beberapa berkas masukan, nilai-nilai yang dikumpulkan akan diakumulasikan (dengan mengutamakan penyembunyian).

Selalu sisakan baris kosong setelah penutup C<--->. Dengan pola pencocokan bergaya paragraf, front matter yang langsung menyambung ke teks isi membentuk satu blok yang melintasi kedua bagian, sehingga pengecualian tidak dapat menekannya (peringatan akan ditampilkan dalam kasus tersebut); nilai-nilai tersebut tetap dianonimkan, tetapi bagian awal itu sendiri akan dikirim untuk diterjemahkan.

=item B<--xlate-glossary>=I<glossary>

Tentukan ID glosarium yang akan digunakan untuk terjemahan. Opsi ini hanya tersedia saat menggunakan mesin DeepL. ID glosarium harus diperoleh dari akun DeepL Anda dan memastikan terjemahan yang konsisten untuk istilah tertentu.

=item B<--xlate-dryrun>

Jangan panggil API terjemahan; sebaliknya, tampilkan, melalui tampilan kemajuan, setiap muatan persis seperti yang akan dikirimkan (setelah anonimisasi dan penyamaran). Berguna untuk memeriksa apa yang dikirimkan oleh sistem dan untuk memperkirakan biaya suatu proses.

=item B<-->[B<no->]B<xlate-progress> (Default: True)

Lihat hasil terjemahan secara real-time pada keluaran STDERR. Payload C<From> ditampilkan sebagaimana dikirimkan, setelah anonimisasi dan penyamaran.

=item B<--xlate-stripe>

Gunakan modul L<App::Greple::stripe> untuk menampilkan bagian yang cocok dengan mode garis zebra. Hal ini berguna ketika bagian yang dicocokkan dihubungkan secara berurutan.

Palet warna dialihkan menurut warna latar belakang terminal. Jika Anda ingin menentukan secara eksplisit, Anda dapat menggunakan B<--xlate-stripe-light> atau B<--xlate-stripe-dark>.

=item B<--xlate-mask>

Lakukan fungsi masking dan tampilkan teks yang dikonversi apa adanya tanpa pemulihan.

=item B<--match-all>

Mengatur seluruh teks file sebagai area target.

=item B<--lineify-cm>

=item B<--lineify-colon>

Dalam kasus format C<cm> dan C<colon>, output dibagi dan diformat baris demi baris. Oleh karena itu, jika hanya sebagian dari suatu baris yang akan diterjemahkan, hasil yang diharapkan tidak dapat diperoleh. Filter ini memperbaiki output yang rusak dengan menerjemahkan bagian dari sebuah baris menjadi output baris per baris yang normal.

Dalam implementasi saat ini, jika beberapa bagian dari suatu baris diterjemahkan, maka akan dikeluarkan sebagai baris independen.

=back

=head1 CACHE OPTIONS

Modul B<xlate> dapat menyimpan teks terjemahan dalam cache untuk setiap file dan membacanya sebelum eksekusi untuk menghilangkan overhead dari permintaan ke server. Dengan strategi cache default C<auto>, modul ini mempertahankan data cache hanya ketika file cache ada untuk file target.

Gunakan B<--xlate-cache=clear> untuk memulai manajemen cache atau untuk membersihkan semua data cache yang ada. Setelah dieksekusi dengan opsi ini, file cache baru akan dibuat jika belum ada dan kemudian secara otomatis dipelihara setelahnya.

=over 7

=item --xlate-cache=I<strategy>

=over 4

=item C<auto> (Default)

Mempertahankan file cache jika sudah ada.

=item C<create>

Buat file cache kosong dan keluar.

=item C<always>, C<yes>, C<1>

Pertahankan cache sejauh targetnya adalah file normal.

=item C<clear>

Hapus data cache terlebih dahulu.

=item C<never>, C<no>, C<0>

Jangan pernah menggunakan file cache meskipun ada.

=item C<accumulate>

Secara default, data yang tidak digunakan akan dihapus dari file cache. Jika Anda tidak ingin menghapusnya dan menyimpannya di dalam file, gunakan C<accumulate>.

=back

=item B<--xlate-update>

Opsi ini memaksa untuk memperbarui file cache meskipun tidak diperlukan.

=back

=head1 COMMAND LINE INTERFACE

Anda dapat dengan mudah menggunakan modul ini dari baris perintah dengan menggunakan perintah C<xlate> yang disertakan dalam distribusi. Lihat halaman manifes C<xlate> untuk penggunaan.

Perintah C<xlate> mendukung opsi panjang gaya GNU seperti C<--to-lang>, C<--from-lang>, C<--engine>, dan C<--file>. Gunakan C<xlate -h> untuk melihat semua opsi yang tersedia.

Perintah C<xlate> bekerja bersama dengan lingkungan Docker, jadi meskipun Anda tidak memiliki apa pun yang terinstal, Anda dapat menggunakannya selama Docker tersedia. Gunakan opsi C<-D> atau C<-C>.

Operasi-operasi Docker ditangani oleh L<App::dozo>, yang juga dapat digunakan sebagai perintah mandiri. Perintah C<dozo> mendukung berkas konfigurasi C<.dozorc> untuk pengaturan kontainer persisten.

Selain itu, karena tersedia makefile untuk berbagai gaya dokumen, penerjemahan ke dalam bahasa lain dapat dilakukan tanpa spesifikasi khusus. Gunakan opsi C<-M>.

Anda juga dapat menggabungkan opsi Docker dan C<make> sehingga Anda dapat menjalankan C<make> di lingkungan Docker.

Menjalankan seperti C<xlate -C> akan meluncurkan sebuah shell dengan repositori git yang sedang berjalan.

Baca artikel bahasa Jepang di bagian L</LIHAT JUGA> untuk detailnya.

=head1 EMACS

Muat file F<xlate.el> yang disertakan dalam repositori untuk menggunakan perintah C<xlate> dari editor Emacs. Fungsi C<xlate-region> menerjemahkan wilayah tertentu. Bahasa default adalah C<EN-US> dan Anda dapat menentukan bahasa yang digunakan dengan argumen awalan.

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

=head1 ENVIRONMENT

=over 7

=item DEEPL_AUTH_KEY

Tetapkan kunci autentikasi Anda untuk layanan DeepL.

=item OPENAI_API_KEY

Kunci otentikasi OpenAI, digunakan oleh mesin B<gpty> versi lama. Mesin B<gpt5> berbasis C<llm> juga membaca variabel ini, tetapi kunci yang disimpan dengan C<llm keys set openai> juga berfungsi.

=item GREPLE_XLATE_CACHE

Tetapkan strategi cache default (lihat L</CACHE OPTIONS>).

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Instal alat baris perintah untuk mesin yang Anda gunakan: C<llm> untuk mesin B<gpt5>, C<deepl> untuk DeepL, C<gpty> untuk mesin GPT lama.

L<https://llm.datasette.io/>

L<https://github.com/DeepLcom/deepl-python>

L<https://github.com/tecolicom/App-gpty>

=head1 SEE ALSO

=head2 MODULES

L<App::Greple::xlate::llm>, L<App::Greple::xlate::deepl>

L<App::dozo> - Runner Docker Generik yang digunakan oleh xlate untuk operasi kontainer

=head2 RELATED MODULES

=over 2

=item * L<App::Greple>

Lihat manual B<greple> untuk detail tentang pola teks target. Gunakan opsi B<--inside>, B<--outside>, B<--include>, B<--exclude> untuk membatasi area pencocokan.

=item * L<App::Greple::update>

Anda dapat menggunakan modul C<-Mupdate> untuk memodifikasi file berdasarkan hasil perintah B<greple>.

=item * L<App::sdif>

Gunakan B<sdif> untuk menampilkan format penanda konflik berdampingan dengan opsi B<-V>.

=item * L<App::Greple::stripe>

Modul Greple B<stripe> yang digunakan oleh opsi B<--xlate-stripe>.

=back

=head2 RESOURCES

=over 2

=item * L<https://hub.docker.com/r/tecolicom/xlate>

Gambar kontainer Docker.

=item * L<https://github.com/tecolicom/getoptlong>

Pustaka C<getoptlong.sh> yang digunakan untuk penguraian opsi dalam skrip C<xlate> dan L<App::dozo>.

=item * L<https://llm.datasette.io/>

Perintah C<llm> yang digunakan oleh mesin B<gpt5> untuk mengakses model LLM.

=item * L<https://github.com/DeepLcom/deepl-python>

DeepL pustaka Python dan perintah CLI.

=item * L<https://github.com/openai/openai-python>

Perpustakaan Python OpenAI

=item * L<https://github.com/tecolicom/App-gpty>

Antarmuka baris perintah OpenAI

=back

=head2 ARTICLES

=over 2

=item * L<https://qiita.com/kaz-utashiro/items/1c1a51a4591922e18250>

Modul Greple untuk menerjemahkan dan mengganti bagian yang diperlukan saja dengan DeepL API (dalam bahasa Jepang)

=item * L<https://qiita.com/kaz-utashiro/items/a5e19736416ca183ecf6>

Menghasilkan dokumen dalam 15 bahasa dengan modul API DeepL (dalam bahasa Jepang)

=item * L<https://qiita.com/kaz-utashiro/items/1b9e155d6ae0620ab4dd>

Lingkungan Docker terjemahan otomatis dengan DeepL API (dalam bahasa Jepang)

=back

=head1 AUTHOR

Kazumasa Utashiro

=head1 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.

=cut
