Language Conventions

Rule

Examples

Docstring — Brazilian Portuguese:

def submit_transcription(audio_path: str) -> str:
    """
    Submete um arquivo de áudio para transcrição assíncrona.

    Args:
        audio_path: Caminho do arquivo de áudio no armazenamento blob.

    Returns:
        Identificador do trabalho de transcrição criado.

    Raises:
        TranscriptionError: Quando o serviço de fala não está disponível.
    """

Source code — English:

class TranscriptionRepository:
    def find_by_status(self, status: JobStatus) -> list[TranscriptionJob]:
        ...

Inline comment explaining intent — Brazilian Portuguese:

# Agrupa por locutor antes de calcular métricas de sobreposição
grouped = group_by_speaker(segments)

Settings — English:

MAX_RETRY_ATTEMPTS = 3
BLOB_CONTAINER_NAME = "audio-uploads"

Checklist

When writing any file, verify:

• All docstrings are written in Brazilian Portuguese
• Project/user-facing documentation (product README, user guides, markdown docs) is written in Brazilian Portuguese
• All identifiers (variables, functions, classes, modules) are English
• Parameter names and type annotations are English
• Configuration keys and environment variable names are English
• Inline comments that explain non-obvious intent use Brazilian Portuguese
• Log messages and exception strings are English