diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ecccc1f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,12 @@ +## Translation PR + +- **Language:** +- **Files translated:** list files +- **Translator:** @yourusername +- **Type:** machine / human + +### Checklist +- [ ] Root English docs (`docs/en/`) untouched +- [ ] Translator credit added to each translated file +- [ ] Links/code blocks checked +- [ ] Native-speaker review requested diff --git a/.github/scripts/auto_translate.py b/.github/scripts/auto_translate.py new file mode 100644 index 0000000..10ace80 --- /dev/null +++ b/.github/scripts/auto_translate.py @@ -0,0 +1,47 @@ +#!/usr/bin/env python3 +from pathlib import Path +import re, os +from deep_translator import GoogleTranslator + +SRC = Path("docs/en") +OUT = Path("docs") +TARGETS = os.environ.get("TARGET_LANGS", "hi,es,fr").split(",") + +FENCE_RE = re.compile(r'(```[\s\S]*?```)', re.MULTILINE) + +def translate_text(text, lang): + paragraphs = re.split(r'\n\s*\n', text) + translator = GoogleTranslator(source='auto', target=lang) + out=[] + for p in paragraphs: + if not p.strip(): + out.append(p) + continue + out.append(translator.translate(p)) + return "\n\n".join(out) + +def protect_and_translate(text, lang): + parts = FENCE_RE.split(text) + out=[] + for part in parts: + if part.startswith("```"): + out.append(part) + else: + out.append(translate_text(part, lang)) + return "".join(out) + +def main(): + for lang in TARGETS: + lang = lang.strip() + if not lang: continue + for src in SRC.rglob("*.md"): + rel = src.relative_to(SRC) + target_dir = OUT / lang / rel.parent + target_dir.mkdir(parents=True, exist_ok=True) + body = src.read_text(encoding="utf-8") + translated = protect_and_translate(body, lang) + (target_dir / rel.name).write_text(translated, encoding="utf-8") + print("Wrote:", target_dir/rel.name) + +if __name__ == "__main__": + main() diff --git a/.github/workflows/translate.yml b/.github/workflows/translate.yml new file mode 100644 index 0000000..46faaa9 --- /dev/null +++ b/.github/workflows/translate.yml @@ -0,0 +1,25 @@ +name: Auto-translate docs +on: + workflow_dispatch: + schedule: + - cron: '0 3 * * 1' + +jobs: + translate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: python-version: '3.11' + - run: pip install deep-translator + - run: python .github/scripts/auto_translate.py + env: + TARGET_LANGS: "hi,es,fr" + - name: Create PR + uses: peter-evans/create-pull-request@v5 + with: + token: ${{ secrets.GITHUB_TOKEN }} + commit-message: "chore(docs): add machine-translated docs" + branch: translation/auto + title: "Auto: add machine-translated docs" + body: "Machine-generated translations. Please review." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e27755a..8fcac6d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -99,3 +99,11 @@ Once your PR is ready: +### Translating docs (new) + +We welcome translators! To help organize translation work: + +- Claim or open issues labeled `translation`. +- Follow the rules in `TRANSLATIONS.md`. +- Mark machine-generated PRs with the label `machine-translation`. +- Request native-speaker reviewers before merging. diff --git a/README.md b/README.md index 1f306f6..9b386e2 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,2 @@ -# 🌐 HacktoberBlog - Spring Boot Backend - -Welcome to the backend repository for **HacktoberBlog** – a simple blogging platform built with **Spring Boot** and **Firebase Firestore**. This project is beginner-friendly and perfect for your first open-source contribution during **Hacktoberfest**! 🎉 - ---- - -## 📌 Project Overview - -This is the **backend service** for HacktoberBlog. It provides APIs to: - -- 👤 Create, update, delete, and list users -- 📝 Create and retrieve blog posts -- ❤️ Like a blog -- 💬 Comment on a blog -- 📧 Send welcome emails to new users - -Built using: -- Java + Spring Boot -- Firebase Firestore (NoSQL DB) -- Firebase Admin SDK -- Spring Boot Actuator & Mail -- Lombok for clean code - ---- - -## 🗂️ Project Structure - -``` -src/ -└── main/ -├── java/com/hacktober/blog/ -│ ├── blog/ → Blog service logic -│ ├── user/ → User service logic -│ ├── email/ → Email service logic -│ ├── config/ → Firebase initialization -│ └── utils/ → Utility functions (e.g., password encoding) -└── resources/ -└── application.properties -``` - ---- - -## 📘 API Documentation - -Interactive API documentation is available out of the box thanks to Swagger UI and the generated OpenAPI specification. - -1. Run the application locally: - -```bash -./mvnw spring-boot:run -``` - -2. Open [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) in your browser to explore and try the endpoints. - -The raw OpenAPI document can be downloaded from [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs) for integration with other tools. - ---- -## 🚀 Getting Started - -### 1. Prerequisites - -- Java 17+ -- Maven -- Email SMTP (Gmail or others) -- Firebase Project (Firestore + Service Account) - -### 2. Clone the repo - -```bash -git clone https://github.com/HacktoberBlog/SpringBootBackend.git -cd SpringBootBackend -``` - -### 3. Firebase Setup - -- Go to Firebase Console - -- Create a project - -- Enable Firestore - -- Generate a Service Account Key JSON file - -- Save the file in a secure path, e.g., /etc/secrets/firebaseServiceAccountKey.json - -### 4. Configure Email - -Edit src/main/resources/application.properties: - -``` -spring.mail.host=smtp.gmail.com -spring.mail.port=587 -spring.mail.username=your_email@gmail.com -spring.mail.password= 16 char app key such as abcd efgh ijkl mnop -spring.mail.properties.mail.smtp.auth=true -spring.mail.properties.mail.smtp.starttls.enable=true -redis.password= your redis db password -``` - -#### Getting Keys/Passwords for Email, DB, etc. -Gmail 16 char App Key: You can get the app key by navigating to google myaccount settings->search app passwords->give an app name-> create and copy the key - -Redis Password: You can create a free db on [Redis](https://redis.io/). Once your db is created, click on the "Connect using Redis CLI, Client, or Insight" button. There you will be able to view your password (view/hide it using eye icon) - - -### 🔑 Setup Secrets (Environment Variables) - -To run the project, you must provide your secrets as environment variables. -These are used in `application.properties` via Spring's placeholder system: - -| Variable Name | Description | Example Value | -|---------------------------------|-----------------------------------------------|--------------------------------| -| `spring.mail.username` | Your email for sending welcome emails. | `your_email@gmail.com` | -| `spring.mail.password` | Your 16-char app key for the email account. | `abcd efgh ijkl mnop` | -| `redis.password` | The password for your Redis database. | `yourRedisDbPassword123` | - - -## ⚠️ **NOTE:** -**🚫 DO NOT PUSH** the changes made in `application.properties`, `RedisConfig`, and `FirestoreService`. -🔒 _Keep your secrets safe!_ 🔒 - -## 🚀 Live Demo -🎉 The project is now LIVE! Check it out here: [HacktoberBlog Deployment](https://springbootbackend-onuz.onrender.com) 🌟 \ No newline at end of file +The full documentation has been moved into `docs/en/README.md` (canonical English docs). +Please edit docs in `docs/en/` and submit translation PRs into `docs//`. diff --git a/TRANSLATIONS.md b/TRANSLATIONS.md new file mode 100644 index 0000000..6e0d0b6 --- /dev/null +++ b/TRANSLATIONS.md @@ -0,0 +1,25 @@ +# TRANSLATIONS + +## Source of truth +- `docs/en/` is the canonical English documentation for the project. +- Keep `docs/en/` synced with any updates to the root README. The root README is a pointer. + +## Path & filenames +- Use ISO-639-1 codes for language folders: `docs/hi/`, `docs/es/`, `docs/fr/`, etc. +- Keep the same filenames and relative paths as `docs/en/`. + +## Workflow +1. Claim an issue "Translate docs/en/ → ". +2. Create a branch: `feat/translate--`. +3. Add translator metadata at top of translated files: + +4. Open a PR, add label `translation` (and `machine-translation` if machine-generated). +5. Request at least one native-speaker review before merging. + +## Quality +- Do not edit files in `docs/en/` except to fix the English source. +- Preserve code blocks, YAML front matter, and links. +- Use `docs/GLOSSARY.md` for consistent terminology. + +## Credits +- Add translator names to the top of each translated file (or maintain a `TRANSLATORS.md`). diff --git a/docs/en/README.md b/docs/en/README.md new file mode 100644 index 0000000..1f306f6 --- /dev/null +++ b/docs/en/README.md @@ -0,0 +1,123 @@ +# 🌐 HacktoberBlog - Spring Boot Backend + +Welcome to the backend repository for **HacktoberBlog** – a simple blogging platform built with **Spring Boot** and **Firebase Firestore**. This project is beginner-friendly and perfect for your first open-source contribution during **Hacktoberfest**! 🎉 + +--- + +## 📌 Project Overview + +This is the **backend service** for HacktoberBlog. It provides APIs to: + +- 👤 Create, update, delete, and list users +- 📝 Create and retrieve blog posts +- ❤️ Like a blog +- 💬 Comment on a blog +- 📧 Send welcome emails to new users + +Built using: +- Java + Spring Boot +- Firebase Firestore (NoSQL DB) +- Firebase Admin SDK +- Spring Boot Actuator & Mail +- Lombok for clean code + +--- + +## 🗂️ Project Structure + +``` +src/ +└── main/ +├── java/com/hacktober/blog/ +│ ├── blog/ → Blog service logic +│ ├── user/ → User service logic +│ ├── email/ → Email service logic +│ ├── config/ → Firebase initialization +│ └── utils/ → Utility functions (e.g., password encoding) +└── resources/ +└── application.properties +``` + +--- + +## 📘 API Documentation + +Interactive API documentation is available out of the box thanks to Swagger UI and the generated OpenAPI specification. + +1. Run the application locally: + +```bash +./mvnw spring-boot:run +``` + +2. Open [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) in your browser to explore and try the endpoints. + +The raw OpenAPI document can be downloaded from [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs) for integration with other tools. + +--- +## 🚀 Getting Started + +### 1. Prerequisites + +- Java 17+ +- Maven +- Email SMTP (Gmail or others) +- Firebase Project (Firestore + Service Account) + +### 2. Clone the repo + +```bash +git clone https://github.com/HacktoberBlog/SpringBootBackend.git +cd SpringBootBackend +``` + +### 3. Firebase Setup + +- Go to Firebase Console + +- Create a project + +- Enable Firestore + +- Generate a Service Account Key JSON file + +- Save the file in a secure path, e.g., /etc/secrets/firebaseServiceAccountKey.json + +### 4. Configure Email + +Edit src/main/resources/application.properties: + +``` +spring.mail.host=smtp.gmail.com +spring.mail.port=587 +spring.mail.username=your_email@gmail.com +spring.mail.password= 16 char app key such as abcd efgh ijkl mnop +spring.mail.properties.mail.smtp.auth=true +spring.mail.properties.mail.smtp.starttls.enable=true +redis.password= your redis db password +``` + +#### Getting Keys/Passwords for Email, DB, etc. +Gmail 16 char App Key: You can get the app key by navigating to google myaccount settings->search app passwords->give an app name-> create and copy the key + +Redis Password: You can create a free db on [Redis](https://redis.io/). Once your db is created, click on the "Connect using Redis CLI, Client, or Insight" button. There you will be able to view your password (view/hide it using eye icon) + + +### 🔑 Setup Secrets (Environment Variables) + +To run the project, you must provide your secrets as environment variables. +These are used in `application.properties` via Spring's placeholder system: + +| Variable Name | Description | Example Value | +|---------------------------------|-----------------------------------------------|--------------------------------| +| `spring.mail.username` | Your email for sending welcome emails. | `your_email@gmail.com` | +| `spring.mail.password` | Your 16-char app key for the email account. | `abcd efgh ijkl mnop` | +| `redis.password` | The password for your Redis database. | `yourRedisDbPassword123` | + + +## ⚠️ **NOTE:** +**🚫 DO NOT PUSH** the changes made in `application.properties`, `RedisConfig`, and `FirestoreService`. +🔒 _Keep your secrets safe!_ 🔒 + +## 🚀 Live Demo +🎉 The project is now LIVE! Check it out here: [HacktoberBlog Deployment](https://springbootbackend-onuz.onrender.com) 🌟 \ No newline at end of file