=encoding utf-8
=head1 NAME
App::Greple::xlate - modul dukungan penerjemahan 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
Modul B<Greple> B<xlate> menemukan blok teks yang diinginkan dan menggantinya dengan teks yang telah diterjemahkan. Saat ini modul DeepL (F<deepl.pm>) dan ChatGPT (F<gpt3.pm>) diimplementasikan sebagai mesin back-end. Dukungan eksperimental untuk gpt-4 dan gpt-4o juga disertakan.
Jika Anda ingin menerjemahkan blok teks normal dalam dokumen yang ditulis dengan 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, 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. Kemudian, ia akan menemukan bagian yang diinginkan dan menggantinya dengan keluaran perintah B<deepl>.
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 C<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-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 dari file `MASKPATTERN` sebagai ekspresi reguler, menerjemahkan string yang cocok dengan itu, dan mengembalikannya setelah diproses. Baris yang dimulai dengan C<#> akan diabaikan.
Pola kompleks dapat ditulis pada beberapa baris dengan garis miring diakhiri dengan baris baru.
Bagaimana teks diubah dengan masking 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)
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 penerjemahan yang akan digunakan. Jika Anda menentukan modul mesin secara langsung, seperti C<-Mxlate::deepl>, Anda tidak perlu menggunakan opsi ini.
Pada saat ini, mesin berikut ini 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 untuk bekerja dengan benar saat ini.
=back
=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. Anda bisa mendapatkan bahasa yang tersedia dengan perintah C<deepl languages> ketika menggunakan mesin B<DeepL>.
=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, dan 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 ditetapkan 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.
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<-->[B<no->]B<xlate-progress> (Default: True)
Lihat hasil terjemahan secara real time dalam output STDERR.
=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.
=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> 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>.
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 autentikasi 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>
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
=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 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-2025 Kazumasa Utashiro.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut