fds-dev 0.0.2

A blazingly fast, structure-aware linter for your documentation, with built-in translation for non-native English speakers.

FDS-Dev (Flamehaven Doc Sanity for Developers)

English | 한국어

A blazingly fast, structure-aware linter for your documentation, supercharged with AI-powered translation.

Built for the global developer community. Write documentation and code comments in your native language, and let FDS-Dev instantly translate it to production-ready English.

Features • Quick Start • Documentation • Contributing • Support

---

The Problem

You are a talented developer from Korea, Japan, China, Germany, or anywhere else in the world. Your code is brilliant, but writing documentation and comments in English is a chore. It slows you down and creates a barrier to sharing your work with the global open-source community.

Existing linters like markdownlint or Vale are great, but they are English-centric. They don't solve this core problem.

The Solution: FDS-Dev

FDS-Dev is two tools in one:

1. A Blazing-Fast Linter: Ensures your documentation has a clean, professional structure.
2. An AI-Powered Translator: Automatically translates your native-language docs and comments into fluent, natural English.

Stop worrying about English. Focus on your code.

Why FDS-Dev

A New Category: Code-Level Internationalization

Traditional linters (markdownlint, Vale) only validate formatting, and conventional translators mangle code blocks or technical terms. FDS-Dev instead treats documentation, code comments, and docstrings as first-class data structures, so non-English-speaking developers can participate in global OSS without rewriting everything in English by hand.

Problems We Actually Solve

• Language barrier: Converts README files, architecture notes, inline comments, and docstrings into production English while protecting the original code structure.
• Documentation integrity: Enforces section ordering, required headers, and other structure rules, so every README has the same professional baseline.

Unique Advantages

1. AI-driven code-aware translation

   • Parses Markdown, Python docstrings, and inline comments via CodeCommentParser, so translations respect code layout and skip code blocks entirely.
   • Preserves CamelCase, snake_case, and other identifiers through TechnicalTermDatabase, keeping API names intact.
   • Scores every translation with an Omega (Ω) quality tensor; low-scoring translations can be retried or rejected automatically.

2. Blazingly fast, structure-aware linting

   • Runs lint jobs in parallel using a persistent cache (.fds_cache.json) so large doc trees finish quickly.
   • Validates structural requirements such as “License section must exist” or “Installation must precede Usage,” not just spelling.

3. Flexible translation backends

   • Default py-googletrans backend works with zero configuration for quick trials.
   • Switch to DeepL, MyMemory, or LibreTranslate in .fdsrc.yaml for higher quality or self-hosted control.

4. Community impact

   • Enables non-English-speaking developers to ship English documentation without losing intent, making it easier to get PRs accepted or run international product launches.
   • Actively-developed roadmap welcomes new contributors; stars, issues, and PRs help define the next wave of code-level localization tooling.

Core Features

• Structure-Aware Linting: Go beyond simple style checks. Enforce section order, require specific headers, and validate the overall structure of your documents.
• Broken Link Audits: Optionally enable the broken-link-check rule to flag missing anchors, absent files, or unreachable URLs before publishing.
• Automated Translation: Translate Markdown files and source code comments from languages like Korean, Chinese, Japanese, and more into English.
• Simple Configuration: A single .fdsrc.yaml file to control everything.
• Built for Speed: Core components written for maximum performance.

Quick Start

pip install --upgrade fds-dev
fds --help

1. Lint your documentation

Check for structural issues in your documentation.

fds lint README.ko.md

2. Translate to English

Translate your Korean README and its comments into a new, global-ready English file.

# Translates README.ko.md -> README.md
fds translate README.ko.md --output README.md

# Translate a source code file's comments in-place
fds translate my_app/main.py --in-place

CLI Commands

• fds lint <path>: Runs the structure-aware lint checks configured in .fdsrc.yaml, including optional rules such as broken-link-check.
• fds translate <path> [--output OUTPUT | --in-place]: Converts Markdown or source files to English, preserving code blocks and identifiers.
• fds translate --help / fds lint --help: Show detailed usage and supported flags.

Broken link validation is controlled entirely via .fdsrc.yaml; once the rule is enabled, fds lint will report missing anchors, absent files, or unreachable URLs just like any other lint error.

Translation Providers

FDS-Dev supports multiple translation providers. You can configure your preferred provider in the .fdsrc.yaml file.

Provider	Default?	API Key	Cost	Quality	Stability	Recommended Use Case
Google Translate (Free)	✅ (Default)	None	Free	High	Unstable¹	Personal projects, quick tests, general docs
DeepL	❌	Required	Limited Free Tier/Paid	Very High	Very High	Production, commercial, official docs
MyMemory	❌	None	Free	Medium	Medium	Simple scripts, temporary use
LibreTranslate	❌	None	Free (Self-hosted)	Medium²	User-managed	Private servers, offline, full control

¹ Uses an unofficial API, which may stop working without notice. ² Quality depends on the model you host yourself.

To use a provider other than the default, configure it in your .fdsrc.yaml file. For providers requiring an API key, it is highly recommended to use environment variables.

Example for DeepL:

# .fdsrc.yaml
translator:
  provider: 'deepl'
  providers:
    deepl:
      # It's recommended to use the FDS_DEEPL_API_KEY environment variable instead.
      api_key: null

Deployment & Automation

Continuous Integration

GitHub Actions automatically runs the test suite across Python 3.9–3.11 and builds release artifacts for every push and pull request targeting main. You can find the workflow definition in .github/workflows/ci.yml.

Automated PyPI Releases

Tagging a commit with the v* pattern (for example, v0.2.0) triggers .github/workflows/release.yml, which builds the project with python -m build and publishes the result to PyPI using the PYPI_API_TOKEN secret.

Official Docker Image

Ship the CLI as a container image by using the provided Dockerfile:

docker build -t fds-dev .
docker run --rm fds-dev lint README.md

The image installs the package globally and exposes the fds entrypoint, so any CLI command can be run directly.

Contributing

FDS-Dev is in early development. Contributions are welcome!

See CONTRIBUTING.md for the detailed workflow, release checklist, and ASCII compatibility notes.

We welcome contributions from the community! Here's how you can help:

How to Contribute

1. Report Issues: Found a bug? Open an issue
2. Suggest Features: Have an idea? Share it in Discussions
3. Submit Pull Requests: Fix bugs or add features
4. Improve Documentation: Help make our docs even better

Development Setup

# Clone repository
git clone https://github.com/flamehaven01/FDS-Dev.git
cd FDS-Dev

# Install in development mode
pip install -e .

# Run tests
pytest tests/ -v

# Run linter
flake8 fds_dev/

Code Quality Standards

• Test coverage ≥ 90%
• All tests passing (100/105 expected)
• Follow PEP 8 style guide
• Add docstrings for public APIs
• Update documentation for new features

---

Support

Documentation

• Translation Algorithm - Complete pipeline explanation
• Architecture Guide - System design documentation
• Troubleshooting - Common issues and solutions

Get Help

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Email: [e-mail]

Community

• Website: flamehaven.space
• Repository: github.com/flamehaven01/FDS-Dev

---

License

MIT License - see LICENSE file for details.

---

About Flamehaven × FDS-Dev

English: FDS-Dev is Flamehaven’s code-level internationalization platform that lets non-English-speaking developers lint, translate, and publish documentation without breaking code structure. We guard identifiers, score translations with an Omega tensor, and ship blazing-fast structural linting so every README feels professional. Stars, issues, and pull requests directly shape the future of multilingual development workflows—join us to expand global open source collaboration.

한국어: FDS-Dev는 Flamehaven이 만든 코드 레벨 국제화 플랫폼으로, 영어가 익숙하지 않은 개발자가 문서 구조를 지키면서 번역하고 린트하도록 돕습니다. 기술 용어를 보존하고 Omega 품질 점수로 번역을 검증하며, 초고속 구조 린팅으로 모든 README가 전문성을 갖추도록 이끕니다. 여러분의 Star, Issue, PR 하나하나가 다국어 개발 워크플로를 완성하는 여정에 직접적인 힘이 됩니다. 함께 글로벌 오픈소스 생태계를 넓혀 주세요.

---

Made with ❤️ by Flamehaven

⬆ Back to top