Skip to content

README.md

Latest commit

 

History

History
136 lines (95 loc) · 3.92 KB

README.md

File metadata and controls

136 lines (95 loc) · 3.92 KB

C Lumen

CI License

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