Cara Menerjemahkan Dokumen Teknis Tanpa Merusak Kode

TABLE OF CONTENTS

Dokumentasi teknis sangat ketat: satu kode fence yang rusak, placeholder, atau anchor yang salah bisa menyebabkan build gagal, membingungkan pembaca, atau membuat copy‑paste tidak berfungsi. Panduan ini memberikan alur kerja yang aman dan dapat diulang untuk menerjemahkan dokumen teknis dengan percaya diri—serta menjaga kode tetap utuh dan dokumen siap diterbitkan.

Untuk siapa panduan ini: penulis teknis, advokat pengembang, dan penerjemah yang mengerjakan dokumentasi developer, panduan API, dan konten bergaya README.

Sekilas:

Pahami apa yang tidak boleh diterjemahkan (kode, key, token)
Jaga sintaks yang diproses oleh alat (fence, kurung, anchor)
Validasi data terstruktur dan tautan setelah diedit
Gunakan otomatisasi untuk mendeteksi masalah sebelum rilis

Persiapan Pra‑Terjemahan

Inventarisasi jenis konten

Markdown (judul, tautan, tabel), blok kode, kode inline
Data terstruktur: potongan JSON/YAML/TOML dan file konfigurasi
Screenshot, diagram, dan visual tersemat

Definisikan token yang tidak boleh diterjemahkan

Path file, nama paket, import, nama API, flag CLI, variabel lingkungan
Placeholder dan variabel: {count}, %s, $HOME, {{token}}
Nama file dan ekstensi: config.yaml, .env, .md, .json

Tetapkan aturan konsistensi

Glosarium/termbase untuk istilah domain dan nama produk
Panduan gaya: nada, tingkat formalitas, tanda baca, penulisan huruf, aturan judul
Strategi anchor/slug per lokal (stabil vs lokal)

Siapkan validasi yang aman

Build staging untuk memvalidasi Markdown/tautan setelah setiap batch
Parser/linter untuk JSON/YAML/TOML
Link checker dan anchor validator di CI

Perlindungan Inti

Jangan menerjemahkan kode, identifier, key, nama file, variabel lingkungan, atau flag.
Jaga tanda baca dan sintaks yang diproses oleh alat (backtick, kurung, pipe).
Pertahankan whitespace penting: indentasi untuk kode dan struktur daftar.
Gunakan blok kode dengan tag bahasa secara konsisten (js, bash, dll.).
Lebih baik gunakan catatan penerjemah daripada “memperbaiki” logika kode—tandai masalah ke maintainer.

Blok Kode dan Kode Inline

Jaga pagar kode, petunjuk bahasa, dan konten tetap utuh. Terjemahkan hanya komentar dan string yang dapat dibaca manusia jika diperlukan.

Contoh—aman vs tidak aman:

// AMAN: Hanya komentar yang dilokalkan
// Mendapatkan token pengguna
import { getToken } from "@acme/sdk";
const token = await getToken();

// TIDAK AMAN: Jangan terjemahkan identifier/import/nama paket
// import { obtenirJeton } from "@acme/sdk"; // ❌

Kode inline harus tetap verbatim:

Baik: “Jalankan npm install -g acme-cli lalu acme login.”
Buruk: “Jalankan npm install -g acme-cli lalu acme connexion.” ❌

Validasi copy‑pasteability: Jika pembaca menyalin cuplikan apa pun, seharusnya berjalan seperti sumber aslinya.

Placeholder dan ICU MessageFormat

Pertahankan placeholder persis seperti aslinya, termasuk spasi dan tanda baca di sekitarnya.

# Jangan ubah token atau spasi
echo "Memproses {count} file"   # ✅
echo "Memproses { count } file" # ❌ menambah spasi di dalam kurung

Contoh ICU:

{count, plural,
  =0 {Tidak ada pesan}
  one {# pesan}
  other {# pesan}
}

Jangan ubah kunci (count, one, other).
Terjemahkan hanya bagian yang dapat dibaca manusia (“pesan”, “pesan”).
Jangan menambah atau mengurangi kategori plural tanpa panduan produk.

Tautan, Anchor, dan Slug

Jaga sintaks tautan Markdown dan strategi resolusi tetap konsisten.

[Baca panduan API](/api/getting-started)  
[Lihat bagian konfigurasi](#configuration)

Terjemahkan teks tautan jika diperlukan; berhati-hati dengan URL dan anchor.
Anchor: bisa mempertahankan anchor stabil di semua lokal atau menghasilkan anchor per lokal dan memperbarui referensi sesuai.
Pastikan jalur relatif dan anchor hash tetap dapat diakses setelah diterjemahkan.
Jangan terjemahkan ekstensi file atau parameter query.

Data Terstruktur (JSON/YAML/TOML)

Terjemahkan hanya nilai—jangan pernah kunci, tipe, atau struktur. Selalu parse ulang setelah mengedit.

JSON:

{
  "title": "Panduan Pengguna",
  "cta": "Mulai Sekarang",
  "limits": { "max": 5, "unit": "permintaan/detik" }
}

Kunci seperti title, cta, limits, max harus tetap tidak berubah.
Angka, boolean, dan null tetap sebagai tipe, bukan kata.

YAML (perhatikan folded scalars):

note: >
  Baris-baris digabung menjadi satu paragraf.
  Jaga indentasi dan penanda tetap utuh.

Pertahankan tanda kutip, escape, indentasi, dan koma di akhir (jika ada).

Nama Berkas, CLI, dan API

Jangan terjemahkan nama berkas, nama paket, endpoint, atau flag CLI.
Jaga sensitivitas huruf persis seperti sumber (misal, --DryRun vs --dry-run).
Pertahankan perintah apa adanya; tambahkan catatan jika ada perbedaan khusus lokal.

# Benar
kubectl get pods --namespace default

# Salah (flag diterjemahkan) ❌
kubectl get pods --nom-espace defaut

Hal-Hal Penting di Markdown

Tabel: pertahankan pipe dan perataan; jangan pecah kolom.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

Admonisi/catatan: pertahankan penanda yang digunakan oleh alat Anda.
Inline HTML: hindari mengubah tag/atribut.
Catatan kaki: jaga id dan urutannya.
Tanda kutip pintar: gunakan tanda kutip lurus di dalam konteks kode.

Visual dan Aksesibilitas

Lokalkan teks alt untuk makna, bukan isi piksel.
Utamakan tangkapan layar yang netral bahasa (sorot UI, bukan bahasa), atau sediakan set per lokal.
Jaga file sumber diagram (misal, Mermaid) tetap sinkron di semua lokal.
Hindari teks tertanam dalam gambar; eksternalkan keterangan dan label.

SEO dan Metadata

Terjemahkan judul, deskripsi, dan heading dengan kata kunci yang sesuai lokal.
Jaga URL kanonik dan hreflang konsisten dengan aturan situs.
Jangan terjemahkan kunci meta/property atau kunci JSON‑LD.
Selaraskan slug dengan strategi anchor Anda untuk menghindari 404.

Alur Kerja dan Otomasi

Gunakan alur kerja CAT/LLM yang menjaga kode span dan tag tetap utuh.
Kunci terminologi dengan glosarium dan daftar jangan-terjemahkan.
Tambahkan pre-commit hook untuk melakukan linting pada Markdown dan validasi JSON/YAML.
Jalankan pemeriksa tautan dan validator anchor pada setiap PR.
Kelompokkan perubahan dalam bagian kecil yang mudah ditinjau dan lacak perbedaannya.

Saran alat (sesuaikan dengan stack Anda):

Linting Markdown dan pemeriksaan tautan di CI
Langkah parsing JSON/YAML untuk menangkap regresi sintaksis
Paket regex untuk memindai placeholder dan format numerik

QA dan Validasi

Lakukan pemeriksaan berikut sebelum melakukan merge:

Build situs untuk menangkap masalah sintaksis: pnpm build
Pemeriksaan tipe/konten (Astro content collections): pnpm astro check
Pratinjau dan uji coba halaman kunci: pnpm preview
Validasi contoh kode dapat dikompilasi atau dijalankan (jika berlaku)
Jalankan pemeriksa tautan dan anchor; perbaiki 404 atau hash yang rusak

Kesalahan Umum

Secara tidak sengaja menerjemahkan key/placeholder.
Merusak kode fence atau pipe pada tabel.
Melokalkan jalur file, flag, atau nama API.
Mengubah judul tanpa memperbarui tautan anchor.
Memasukkan tanda kutip pintar di dalam kode atau JSON.

Lampiran: Daftar Periksa Cepat

Pra-penerbangan (5 item)

Glosarium dan daftar jangan-terjemahkan sudah siap
Token/placeholder sudah didefinisikan dan dilindungi
Strategi anchor/slug sudah dikonfirmasi
Target tautan sudah dipetakan (internal vs eksternal)
Build staging tersedia

Keamanan contoh kode (5 item)

Fence dan petunjuk bahasa tetap utuh
Identifier/import tidak diubah; komentar hanya dilokalkan
Placeholder dan tanda kutip tetap terjaga
Tes copy-paste berhasil
Potongan kode usang ditandai untuk maintainer

Data terstruktur (5 item)

Key dan tipe tidak diubah
Tanda kutip/escape/indentasi tetap terjaga
Angka dan boolean tetap sebagai tipe aslinya
Parser/linter lolos secara lokal
Diff ditinjau untuk perubahan key yang tidak disengaja

Bacaan terkait