---
name: bilingual-coding-standards
description: "Panduan untuk AI agents menulis kode dalam English dengan naming/comments/docstrings konsisten, dan dokumentasi dalam Bahasa Indonesia sambil mempertahankan istilah teknis English. Gunakan saat AI agents menulis kode, generate dokumentasi, atau menciptakan contoh project."
risk: safe
date_added: "2026-03-04"
---

# Bilingual Coding Standards for AI Agents

## Overview

Skill ini mengajarkan AI agents untuk mengikuti standar bilingual coding:

1. **Code**: Variabel, fungsi, kelas, docstrings ditulis dalam **English**. Comments boleh dalam **English atau Bahasa Indonesia** (sesuai preferensi tim)
2. **Documentation**: Semua dokumentasi user-facing (README, API guides, tutorials) ditulis dalam **Bahasa Indonesia**, tetapi **istilah teknis tetap English**

Standar ini memastikan consistency, readability, dan aksesibilitas global sambil membuat dokumentasi user-friendly dalam Bahasa Indonesia.

## When to Use

Trigger penggunaan skill ini:
- AI agent sedang menulis kode (Python, JavaScript, Go, Rust, etc.)
- AI agent membuat dokumentasi, README, atau API guides
- AI agent generate contoh project atau tutorial code
- AI agent melakukan code review atau memberikan feedback tentang naming/structure
- AI agent membuat docstrings atau comments dalam kode
- Ada pertanyaan tentang mapping antara English technical terms dan Bahasa Indonesia

## Code Standards (English-Required)

### Naming Conventions

**Variables & Functions**: Use `camelCase` atau `snake_case` tergantung language convention, tetapi selalu **English** 

❌ **Bad:**
```python
def hitung_jumlah_user(daftar_pengguna):
    """Menghitung jumlah user dalam list"""
    total_user = 0
    for pengguna in daftar_pengguna:
        total_user += 1
    return total_user
```

✅ **Good:**
```python
def calculate_total_users(user_list):
    """Calculate the total number of users in the given list.
    
    Args:
        user_list: List of user objects
        
    Returns:
        int: Total count of users
    """
    total_users = 0
    for user in user_list:
        total_users += 1
    return total_users
```

### Classes & Modules

Classes use `PascalCase`, modules use `snake_case` (English):

❌ **Bad:**
```python
# file: pemroses_data.py
class PemrosesData:
    pass

class sistem_rekomendasi:
    pass
```

✅ **Good:**
```python
# file: data_processor.py
class DataProcessor:
    pass

class RecommendationSystem:
    pass
```

### Comments & Docstrings

**Docstrings harus dalam English**, tetapi **comments boleh dalam English atau Bahasa Indonesia**:

**Docstrings (selalu English):**
- Function/method docstrings
- Class docstrings
- Module-level docstrings

**Inline Comments (English atau Bahasa Indonesia):**
- Bebas pilih sesuai preferensi atau konsistensi tim
- Gunakan bahasa yang paling jelas menjelaskan logika

❌ **Bad:**
```python
def process_order(order_id):
    # Mengambil order dari database
    order = db.get_order(order_id)
    # Validasi apakah order valid
    if not order:
        raise ValueError("Order tidak ditemukan")  # Error message dalam Bahasa Indonesia (JANGAN)
    # Hitung total harga dengan pajak
    total_price = order.amount * 1.1
    return total_price
```

✅ **Good (dengan comments Bahasa Indonesia):**
```python
def process_order(order_id):
    """Process an order and calculate the total price with tax.
    
    Args:
        order_id: Unique identifier of the order
        
    Returns:
        float: Total price including tax (10%)
        
    Raises:
        ValueError: If order is not found
    """
    # Mengambil order dari database
    order = db.get_order(order_id)
    
    # Validasi apakah order valid
    if not order:
        raise ValueError("Order not found")
    
    # Hitung total harga dengan pajak 10%
    total_price = order.amount * 1.1
    return total_price
```

✅ **Good (dengan comments English):**
```python
def process_order(order_id):
    """Process an order and calculate the total price with tax.
    
    Args:
        order_id: Unique identifier of the order
        
    Returns:
        float: Total price including tax (10%)
        
    Raises:
        ValueError: If order is not found
    """
    # Retrieve order from database
    order = db.get_order(order_id)
    
    # Validate order existence
    if not order:
        raise ValueError("Order not found")
    
    # Calculate total price with 10% tax
    total_price = order.amount * 1.1
    return total_price
```

### Code Structure

- Use clear file organization: `src/`, `tests/`, `docs/`, `utils/`
- Organize functions logically within modules
- Group related functionality together
- Use English for package/module names

## Documentation Standards (Bahasa Indonesia)

### README & Guides

Dokumentasi ditulis dalam **Bahasa Indonesia yang natural**, tetapi istilah teknis tetap **English**:

❌ **Bad:**
```markdown
# Aplikasi Pemroses Data

Aplikasi ini adalah sistem yang digunakan untuk memproses data dari bermacam-macam 
sumber data yang berbeda dan menghasilkan laporan yang komprehensif.

Fitur:
- Baca: Membaca file CSV dan JSON
- Proses: Data preprocessing dan transformasi
- Hasilkan: Generate report dalam format PDF dan Excel
```

✅ **Good:**
```markdown
# Aplikasi Pemroses Data

Aplikasi ini memproses data dari berbagai sumber dan menghasilkan laporan komprehensif 
dalam format PDF dan Excel.

## Fitur Utama

- **CSV & JSON Import**: Mendukung impor data dari file CSV dan JSON
- **Data Preprocessing**: Normalisasi, cleaning, dan transformasi data otomatis
- **Report Generation**: Generate laporan dalam format PDF dan Excel dengan visualisasi
- **API Integration**: REST API untuk integrasi dengan sistem lain

## Instalasi

```bash
uv add data-processor
```

## Quickstart

```python
from data_processor import DataProcessor

processor = DataProcessor()
result = processor.process_file('data.csv')
processor.export_report(result, format='pdf')
```

## Dokumentasi Lengkap

Lihat [API Documentation](docs/api.md) untuk referensi lengkap.
```

### Key Rules

1. **Bahasa Indonesia natural**: Gunakan bahasa yang mudah dipahami, hindari terjemahan literal yang kaku
2. **Istilah teknis tetap English**: `algorithm`, `function`, `API`, `database`, `framework`, `library` dst.
3. **Tidak perlu diterjemahkan**: Architecture, pattern, async, endpoint, payload, schema, validation, etc.
4. **Contoh kode tetap English**: Semua code block dalam dokumentasi pun English

## English-to-Indonesian Technical Terms Mapping

Panduan untuk AI agents tentang kapan menggunakan istilah English vs. Bahasa Indonesia dalam dokumentasi:

| English Term | Indonesian | Penggunaan dalam Docs |
|---|---|---|
| algorithm | algoritma | "algoritma sorting", "algoritma machine learning" |
| array | array/larik | "array of objects", atau "larik data" (optional) |
| async | async | "async function", bukan "fungsi asinkron" |
| authentication | autentikasi | "sistem autentikasi", "login authentication" |
| decorator | decorator | "Python decorator", bukan "penghias" |
| endpoint | endpoint | "REST endpoint /users", bukan "titik akhir" |
| framework | framework | "Django framework", bukan "kerangka kerja" |
| function | fungsi | "fungsi calculate_total()", "function yang pure" |
| loop | loop | "for loop", bukan "perulangan" (kecuali konteks reguler) |
| method | method | "class method", "HTTP method POST" |
| module | modul | "modul auth", "module dalam package" |
| parameter | parameter | "function parameter", "parameter validasi" |
| payload | payload | "request payload", "data payload" |
| pipeline | pipeline | "data pipeline", "CI/CD pipeline" |
| query | query | "database query", "query parameter" |
| schema | schema | "database schema", "JSON schema" |
| validation | validasi | "input validation", "form validation" |
| variable | variabel | "variabel global", "local variable" |

**Guideline:**
- Jika istilah sudah universal digunakan dalam industri Indonesia (async, API, database), gunakan English
- Jika ada padanan Bahasa Indonesia yang natural dan sering digunakan (autentikasi, variabel), boleh gunakan Bahasa Indonesia dengan bantuan English term sebagai referensi
- Consistency rules: Pilih satu dan pakai consistent dalam satu dokumen

## Code Review Checklist for AI Agents

Gunakan checklist ini saat AI agents melakukan code generation atau code review:

### Code Checklist

- [ ] Semua nama variabel dalam **English** (camelCase atau snake_case sesuai convention)
- [ ] Semua nama function/method dalam **English** (clear dan deskriptif)
- [ ] Semua nama class dalam **PascalCase English**
- [ ] Semua docstrings tersedia dan dalam **English**
- [ ] Comments dalam **English atau Bahasa Indonesia** yang jelas (pastikan consistent)
- [ ] Tidak ada Bahasa Indonesia dalam nama variabel, function, atau class
- [ ] Import statements dan module names dalam **English**
- [ ] Error messages dan logging messages dalam **English** (jangan Bahasa Indonesia)
- [ ] File names dan directories dalam **English lowercase** (snake_case atau kebab-case)

### Documentation Checklist

- [ ] README/guides ditulis dalam **Bahasa Indonesia yang natural**
- [ ] Istilah teknis tetap **English** (jangan diterjemahkan)
- [ ] Tidak ada grammar error Bahasa Indonesia
- [ ] Contoh kode dalam dokumentasi tetap **English**
- [ ] Tutorial dan guides mudah diikuti dan tidak kaku
- [ ] API documentation jelas menjelaskan parameters dan return values
- [ ] Links dan references akurat
- [ ] Judul dan headings konsisten dengan tone professional

## Common Pitfalls for AI Agents

❌ **Jangan:**
- Gunakan Bahasa Indonesia dalam nama variabel, function, class, atau docstrings
- Tulis error messages atau logging dalam Bahasa Indonesia
- Terjemahkan technical terms terlalu literal (contoh: "algorithm" → "Algoritma" dengan capital A dalam konteks dokumentasi regular)
- Tulis dokumentasi dalam English campuran dengan Bahasa Indonesia

✅ **Lakukan:**
- Pisahkan dengan jelas: Code (English) vs. Documentation (Indonesian)
- Pertahankan istilah teknis dalam English untuk konsistensi global
- Buat dokumentasi user-friendly dalam Bahasa Indonesia
- Comments boleh Bahasa Indonesia atau English, tapi pastikan consistent dalam satu file
- Error messages selalu dalam English
- Docstrings selalu dalam English

## Example: End-to-End Good Practice

**File: `src/user_service.py` (Code - English)**
```python
"""User service module for managing user operations.

This module provides core functionality for user creation, retrieval, and management.
"""

class UserService:
    """Service class for user-related operations."""
    
    def create_user(self, email, username):
        """Create a new user with given email and username.
        
        Args:
            email: User's email address
            username: User's desired username
            
        Returns:
            dict: Created user object with id, email, username
        """
        new_user = {
            'id': self.generate_id(),
            'email': email,
            'username': username
        }
        return new_user
```

**File: `docs/user-guide.md` (Documentation - Indonesian)**
```markdown
# Panduan Layanan User

Layanan ini memungkinkan Anda mengelola user dalam sistem. Anda dapat membuat user baru, 
mencari user berdasarkan email, dan memperbarui informasi user.

## Membuat User Baru

Gunakan method `create_user()` untuk membuat user baru:

```python
service = UserService()
user = service.create_user('user@example.com', 'john_doe')
```

Method ini akan mengembalikan object user dengan ID unik, email, dan username yang sudah disimpan.

## Referensi API Lengkap

Lihat [API Documentation](../src/user_service.py) untuk dokumentasi lengkap semua methods.
```

---

**Catatan untuk AI Agents:**
Skill ini adalah panduan implementasi bilingual coding. Setiap kali Anda membuat kode atau dokumentasi, 
pastikan mengikuti standar ini dengan konsisten. Perhatikan checklist sebelum finalize output.
