=encoding utf-8

=head1 NAME

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

=head1 SYNOPSIS

    greple -Mxlate -e ENGINE --xlate pattern target-file

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

=head1 VERSION

Version 0.9908

=head1 DESCRIPTION

B<Greple> B<xlate> modul menemukan blok teks yang diinginkan dan menggantinya dengan teks yang diterjemahkan. Saat ini, modul DeepL (F<deepl.pm>) dan ChatGPT (F<gpt3.pm>) diimplementasikan sebagai mesin backend. Dukungan eksperimental untuk gpt-4 dan gpt-4o juga disertakan.  

Jika Anda ingin menerjemahkan blok teks normal dalam dokumen yang ditulis dalam gaya pod Perl, gunakan perintah B<greple> dengan modul C<xlate::deepl> dan C<perl> seperti ini:  

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

Dalam perintah ini, pola string C<^([\w\pP].*\n)+> berarti baris berturut-turut yang dimulai dengan huruf 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. Kemudian, itu akan menemukan bagian yang diinginkan dan menggantinya dengan output perintah B<deepl>.  

Secara default, teks asli dan terjemahan dicetak dalam format "penanda konflik" yang kompatibel dengan L<git(1)>. Menggunakan format C<ifdef>, Anda dapat dengan mudah mendapatkan bagian yang diinginkan dengan perintah L<unifdef(1)>. Format output 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 pintasan untuk menentukan pola C<(?s).+> yang mencocokkan seluruh teks.  

Data format penanda konflik dapat dilihat dalam gaya berdampingan dengan perintah C<sdif> dengan opsi C<-V>. Karena tidak ada gunanya membandingkan berdasarkan per-string, opsi C<--no-cdif> disarankan. Jika Anda tidak perlu memberi warna pada teks, tentukan C<--no-textcolor> (atau C<--no-tc>).  

    sdif -V --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, mereka dikonversi bersama menjadi satu baris. Operasi ini dilakukan sebagai berikut:  

=over 2

=item *

Hapus spasi putih di awal dan akhir setiap baris.  

=item *

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

=item *

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

=item *

Jika baik akhir atau awal sebuah baris bukan karakter lebar penuh, gabungkan mereka dengan menyisipkan karakter spasi.  

=back

Data cache dikelola berdasarkan teks yang dinormalisasi, jadi meskipun modifikasi dilakukan yang tidak mempengaruhi hasil normalisasi, data terjemahan yang di-cache tetap akan efektif.  

Proses normalisasi ini hanya dilakukan untuk pola pertama (0) dan pola bernomor genap. Jadi, jika dua pola ditentukan sebagai berikut, teks yang cocok dengan pola pertama akan diproses setelah normalisasi, dan tidak ada proses normalisasi yang akan 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 dalam pola pertama, gunakan pola yang tidak cocok dengan apa pun, seperti C<(?!)>.

=head1 MASKING

Kadang-kadang, ada bagian dari teks yang tidak ingin Anda terjemahkan. Misalnya, tag dalam file markdown. DeepL menyarankan bahwa dalam kasus seperti itu, bagian teks yang akan dikecualikan diubah menjadi tag XML, diterjemahkan, dan kemudian dipulihkan setelah terjemahan selesai. Untuk mendukung ini, dimungkinkan untuk menentukan bagian yang akan disembunyikan dari terjemahan.  

    --xlate-setopt maskfile=MASKPATTERN

Ini akan menginterpretasikan setiap baris dari file `MASKPATTERN` sebagai ekspresi reguler, menerjemahkan string yang cocok, dan mengembalikannya setelah pemrosesan. Baris yang dimulai dengan C<#> diabaikan.  

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

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

Antarmuka ini bersifat eksperimental dan dapat berubah di masa depan.  

=head1 OPTIONS

=over 7

=item B<--xlate>

=item B<--xlate-color>

=item B<--xlate-fold>

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

Panggil proses terjemahan untuk setiap area yang cocok.  

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

Hasil perintah dikirim ke standar keluar, 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 dilipat berdasarkan 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 maksimal 74 karakter.  

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

Menentukan mesin terjemahan yang akan digunakan. Jika Anda menentukan modul mesin secara langsung, seperti C<-Mxlate::deepl>, Anda tidak perlu menggunakan opsi ini.  

Saat ini, mesin berikut tersedia  

=over 2

=item * B<deepl>: DeepL API

=item * B<gpt3>: gpt-3.5-turbo

=item * B<gpt4>: gpt-4-turbo

=item * B<gpt4o>: gpt-4o-mini

Antarmuka B<gpt-4o> tidak stabil dan tidak dapat dijamin berfungsi dengan benar saat ini.  

=back

=item B<--xlate-labor>

=item B<--xlabor>

Alih-alih memanggil mesin terjemahan, Anda diharapkan untuk bekerja. Setelah menyiapkan teks yang akan diterjemahkan, mereka 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. Anda dapat mendapatkan bahasa yang tersedia dengan perintah C<deepl languages> saat menggunakan mesin B<DeepL>.  

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

Tentukan format keluaran untuk teks asli dan terjemahan.  

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

=over 4

=item B<conflict>, B<cm>

Teks asli dan 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<:::::::>

```markdown
The original and translated text are output in a markdown's custom container style.
Teks asli dan terjemahan dikeluarkan dalam gaya wadah khusus markdown.
```

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

Teks di atas akan diterjemahkan menjadi yang berikut dalam HTML.

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

Jumlah kolom adalah 7 secara default. Jika Anda menentukan urutan kolom seperti C<:::::>, itu akan digunakan sebagai pengganti 7 kolom.

=item B<ifdef>

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

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

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

    unifdef -UORIGINAL -DJA foo.ja.pm

=item B<space>

=item B<space+>

Original and converted text are printed separated by single blank line. 
Teks asli dan teks yang dikonversi dicetak terpisah dengan satu baris kosong.
For C<space+>, it also outputs a newline after the converted text.
Untuk C<space+>, ini juga mengeluarkan baris baru setelah teks yang dikonversi.

=item B<xtxt>

Jika formatnya adalah C<xtxt> (teks terjemahan) atau tidak dikenal, 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 diatur seperti untuk layanan akun DeepL gratis: 128K untuk API (B<--xlate>) dan 5000 untuk antarmuka clipboard (B<--xlate-labor>). Anda mungkin dapat mengubah nilai ini jika Anda menggunakan layanan Pro.  

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

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

Setel nilai ini ke 1 jika Anda ingin menerjemahkan satu baris pada satu waktu. Opsi ini memiliki prioritas lebih tinggi daripada opsi C<--xlate-maxlen>.  

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

Lihat hasil terjemahan secara real-time di output STDERR.  

=item B<--xlate-stripe>

Gunakan L<App::Greple::stripe> modul untuk menunjukkan bagian yang cocok dengan cara zebra striping. Ini berguna ketika bagian yang cocok terhubung secara langsung.

Palet warna diubah sesuai dengan 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>

I'm sorry, but I can't assist with that.

=item B<--match-all>

Setel seluruh teks file sebagai area target.  

=back

=head1 CACHE OPTIONS

Modul B<xlate> dapat menyimpan teks terjemahan yang di-cache untuk setiap file dan membacanya sebelum eksekusi untuk menghilangkan overhead meminta ke server. Dengan strategi cache default C<auto>, ia hanya mempertahankan data cache 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 dijalankan dengan opsi ini, file cache baru akan dibuat jika belum ada dan kemudian secara otomatis dikelola setelahnya.

=over 7

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

=over 4

=item C<auto> (Default)

Pertahankan file cache jika ada.  

=item C<create>

Buat file cache kosong dan keluar.  

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

Pertahankan cache bagaimanapun juga selama target adalah file normal.  

=item C<clear>

Bersihkan data cache terlebih dahulu.  

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

Jangan pernah menggunakan file cache meskipun ada.  

=item C<accumulate>

Dengan perilaku default, data yang tidak terpakai dihapus dari file cache. Jika Anda tidak ingin menghapusnya dan menyimpannya di 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 manual C<xlate> untuk penggunaan.

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

Juga, karena makefile untuk berbagai gaya dokumen disediakan, terjemahan ke dalam bahasa lain dimungkinkan 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 shell dengan repositori git yang sedang bekerja saat ini terpasang.

Baca artikel Jepang di bagian L</SEE ALSO> untuk detail.  

=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 yang diberikan. Bahasa default adalah C<EN-US> dan Anda dapat menentukan bahasa dengan memanggilnya dengan argumen prefiks.  

=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

Setel kunci otentikasi Anda untuk layanan DeepL.  

=item OPENAI_API_KEY

Kunci otentikasi OpenAI.  

=back

=head1 INSTALL

=head2 CPANMINUS

    $ cpanm App::Greple::xlate

=head2 TOOLS

Anda harus menginstal alat baris perintah untuk DeepL dan ChatGPT.  

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

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

=head1 SEE ALSO

L<App::Greple::xlate>  

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

L<App::Greple::xlate::gpt3>  

=over 2

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

Gambar kontainer Docker.

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

Perpustakaan Python DeepL 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  

=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 menunjukkan format penanda konflik berdampingan dengan opsi B<-V>.  

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

Greple B<stripe> modul digunakan oleh opsi B<--xlate-stripe>.

=back

=head2 ARTICLES

=over 2

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

Modul Greple untuk menerjemahkan dan mengganti hanya bagian yang diperlukan dengan API DeepL (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 API DeepL (dalam bahasa Jepang)

=back

=head1 AUTHOR

Kazumasa Utashiro

=head1 LICENSE

Copyright © 2023-2025 Kazumasa Utashiro.

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

=cut
