C Lumen

C Lumen is a multilingual source-to-source prepass for C/C++ that enables developers to write localized keywords in Spanish (es) and Chinese (zh) while compiling with standard Clang/GCC. The system is deterministic, safe, and editor-agnostic.

What is C Lumen?

C Lumen provides keyword-only localization for C/C++ code. It translates language keywords (like if → si in Spanish, 如果 in Chinese) while preserving all identifiers, headers, and library symbols. This allows developers to write code in their native language while maintaining full compatibility with existing build systems and toolchains.

Safety Guarantees

• NFC Normalization: All input is normalized to Unicode NFC form
• Bidirectional Override Protection: Rejects potentially dangerous Unicode bidi overrides
• Confusable Detection: Warns about visually similar characters that could cause security issues
• Deterministic Output: Same input always produces the same canonical output

Quick Start

Installation

# Build from source
git clone https://github.com/c-lumen/c-lumen.git
cd c-lumen
cargo build --release

Basic Usage

# Translate Spanish keywords to canonical C++
clumen apply --lang es --in examples/ahorcado_es.clumen.c --out build/ahorcado.c

# Compile the canonical output
cc build/ahorcado.c -o build/ahorcado && ./build/ahorcado

VS Code Setup

1. Install the C Lumen extension from the VS Code marketplace
2. Open a .clumen.c or .clumen.cpp file
3. Enjoy syntax highlighting and semantic tokens for localized keywords

JetBrains IDEs

1. Go to Settings → Editor → TextMate Bundles
2. Import the textmate-bundle/c-lumen.tmLanguage.json file
3. Restart your IDE

CMake Integration

Use the provided CMake helper for seamless build system integration:

include(tools/cmake/ClumenPrepass.cmake)

# Add your localized source files
clumen_translate(TRANSLATED_SOURCES
    src/main.clumen.cpp
    src/utils.clumen.c
)

# Use the translated sources in your target
add_executable(myapp ${TRANSLATED_SOURCES})

Supported Languages

Spanish (es)

• si → if
• sino → else
• mientras → while
• para → for
• retornar → return
• And many more...

Chinese (zh)

• 如果 → if
• 否则 → else
• 当 → while
• 为 → for
• 返回 → return
• And many more...

Examples

Check out the examples/ directory for complete working examples:

• ahorcado_es.clumen.c - Hangman game with Spanish keywords
• 排序_zh.clumen.cpp - Sorting algorithm with Chinese keywords

Policy: What Gets Translated

✅ Translated:

• Language keywords (if, while, for, etc.)
• Preprocessor directives (#include → #incluir)

❌ NOT Translated:

• Function names
• Variable names
• Header file names
• Library symbols
• API names

Security

C Lumen includes several security measures:

• Unicode normalization prevents canonicalization attacks
• Bidirectional override detection prevents text direction attacks
• Confusable character detection warns about potential spoofing
• Source maps enable precise error reporting

See SECURITY.md for detailed security information.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Adding new keywords
• Extending language support
• Running tests
• Code of conduct

License

C Lumen is licensed under the Apache License 2.0. See LICENSE for details.

Roadmap

• Additional language support (French, German, Japanese)
• Clangd integration for enhanced diagnostics
• Git clean/smudge filters for transparent localization
• WebAssembly tokenizer for browser-based development