Skip to content

Commit ec86cd0

Browse files
em3sem3s
committed
Merge remote-tracking branch 'origin/main' into init/global-async-mode
2 parents 79fe955 + e7e4eeb commit ec86cd0

51 files changed

Lines changed: 2846 additions & 752 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/translation.yml‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
name: Translation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "website/src/content/docs/**"
8+
- "!website/src/content/docs/ko/**"
9+
- "website/i18n/tm/**"
10+
- ".github/workflows/translation.yml"
11+
12+
pull_request:
13+
paths:
14+
- "website/src/content/docs/**"
15+
- "!website/src/content/docs/ko/**"
16+
- "website/i18n/tm/**"
17+
- ".github/workflows/translation.yml"
18+
19+
workflow_dispatch:
20+
inputs:
21+
build:
22+
description: "Build and create translation PR (false = validate only)"
23+
type: boolean
24+
default: true
25+
26+
jobs:
27+
translate:
28+
strategy:
29+
matrix:
30+
lang: [ko]
31+
32+
env:
33+
TARGET_LANG: ${{ matrix.lang }}
34+
35+
name: Translate (${{ matrix.lang }})
36+
runs-on: ubuntu-latest
37+
permissions:
38+
contents: write
39+
pull-requests: write
40+
41+
steps:
42+
- name: Checkout
43+
uses: actions/checkout@v4
44+
with:
45+
fetch-depth: 0
46+
47+
- name: Setup Node.js
48+
uses: actions/setup-node@v4
49+
with:
50+
node-version: "20"
51+
52+
- name: Install dependencies
53+
run: npm ci
54+
working-directory: website
55+
56+
- name: Detect trigger mode
57+
id: trigger
58+
run: |
59+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
60+
echo "build=${{ inputs.build }}" >> "$GITHUB_OUTPUT"
61+
elif [ "${{ github.event_name }}" = "pull_request" ]; then
62+
echo "build=false" >> "$GITHUB_OUTPUT"
63+
else
64+
echo "build=true" >> "$GITHUB_OUTPUT"
65+
fi
66+
67+
- name: Build translations
68+
if: steps.trigger.outputs.build == 'true'
69+
run: npm run translate -- --lang "$TARGET_LANG" build
70+
working-directory: website
71+
72+
- name: Create translation PR
73+
if: steps.trigger.outputs.build == 'true'
74+
uses: peter-evans/create-pull-request@v7
75+
with:
76+
branch: i18n/${{ env.TARGET_LANG }}/update-translations
77+
commit-message: "docs(i18n): update ${{ env.TARGET_LANG }} translations"
78+
title: "docs(i18n): update ${{ env.TARGET_LANG }} translations"
79+
body: |
80+
Automated ${{ env.TARGET_LANG }} translation update from TM-based pipeline.
81+
82+
This PR was generated by the translation workflow.
83+
delete-branch: true
84+
85+
- name: Validate translations
86+
if: steps.trigger.outputs.build == 'false'
87+
run: npm run translate -- --lang "$TARGET_LANG" validate
88+
working-directory: website
89+
90+
- name: Translation status (affected docs)
91+
if: steps.trigger.outputs.build == 'false'
92+
working-directory: website
93+
run: |
94+
if [ "${{ github.event_name }}" = "pull_request" ]; then
95+
BASE_REF="${{ github.event.pull_request.base.ref }}"
96+
fi
97+
98+
if [ -z "$BASE_REF" ]; then
99+
# Manual dispatch — show all docs
100+
npm run translate -- --lang "$TARGET_LANG" status --format=summary | tee /tmp/translation-status.txt
101+
else
102+
# Map changed TM paths to doc-relative paths
103+
DOCS=$(git diff --name-only "origin/$BASE_REF"...HEAD -- "website/i18n/tm/$TARGET_LANG/" \
104+
| sed "s|^website/i18n/tm/$TARGET_LANG/||;s|\.yaml$|.mdx|")
105+
if [ -n "$DOCS" ]; then
106+
npm run translate -- --lang "$TARGET_LANG" status --format=summary --docs $DOCS | tee /tmp/translation-status.txt
107+
else
108+
echo "No affected documents." | tee /tmp/translation-status.txt
109+
fi
110+
fi
111+
112+
cat /tmp/translation-status.txt >> $GITHUB_STEP_SUMMARY

‎CONTRIBUTING.md‎

Lines changed: 109 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,116 @@ Thank you for your interest in Actionbase. Any form of participation—using the
66

77
New to open source? Look for issues labeled **[good first issue](https://github.com/kakao/actionbase/labels/good%20first%20issue)**.
88

9+
## Development setup
10+
11+
### Prerequisites
12+
13+
- Java 17+
14+
- IntelliJ IDEA (Community or Ultimate)
15+
16+
### Setup
17+
18+
```bash
19+
git clone https://github.com/kakao/actionbase.git
20+
cd actionbase
21+
```
22+
23+
Open in IntelliJ: **File > Open** → select project root.
24+
25+
IntelliJ will auto-import Gradle. Wait for indexing to complete.
26+
27+
### Build
28+
29+
```bash
30+
./gradlew build
31+
```
32+
33+
Or in IntelliJ: **Gradle panel > actionbase > Tasks > build > build**
34+
35+
### Format
36+
37+
Run before committing:
38+
39+
```bash
40+
./gradlew spotlessApply
41+
```
42+
43+
This formats Kotlin/Java code according to project style.
44+
45+
### Run
46+
47+
```bash
48+
./gradlew :server:bootRun
49+
```
50+
51+
Server starts at `http://localhost:8080`.
52+
53+
### Test
54+
55+
```bash
56+
# All tests
57+
./gradlew test
58+
59+
# Specific module
60+
./gradlew :core:test
61+
./gradlew :engine:test
62+
./gradlew :server:test
63+
```
64+
65+
## PR workflow
66+
67+
Fork [kakao/actionbase](https://github.com/kakao/actionbase) on GitHub, then set up remotes:
68+
69+
```bash
70+
git remote rename origin upstream
71+
git remote add origin https://github.com/YOUR_USERNAME/actionbase.git
72+
```
73+
74+
1. Create branch: `git checkout -b feature/your-feature`
75+
2. Make changes
76+
3. Format: `./gradlew spotlessApply`
77+
4. Test: `./gradlew test`
78+
5. Commit: `git commit -m "feat(scope): description"`
79+
6. Push & create PR
80+
981
## Translations
1082

11-
We welcome documentation translations. When submitting translation PRs, please submit **one section (folder) per PR** rather than translating all pages at once. This makes reviews manageable and allows incremental progress.
83+
Translations are managed through Translation Memory (TM) files. Here's how to contribute:
84+
85+
1. **Find documents that need translation.** Run the status command to see coverage (`--lang` defaults to `ko`):
86+
87+
```bash
88+
cd website && npm run translate -- --lang ko status
89+
```
90+
91+
2. **Pick a TM file** in `website/i18n/tm/{lang}/` (e.g. `ko`) and open it in your editor. Each TM file looks like this:
92+
93+
```yaml
94+
meta:
95+
contributors:
96+
- alice
97+
entries:
98+
- source: "What is Actionbase?"
99+
target: "" # ← fill in your translation here
100+
context: heading
101+
- source: "Actionbase is a database for serving user interactions."
102+
target: "" # ← and here
103+
context: paragraph
104+
```
105+
106+
3. **Fill in translations.** Find entries with `target: ""` and add the translated text.
107+
108+
4. **Add your GitHub username** to `meta.contributors`.
109+
110+
5. **(Optional) Preview locally.** Build the translated docs and check the output:
111+
112+
```bash
113+
cd website && npm run translate -- --lang ko build
114+
```
115+
116+
6. **Open a PR.** Please submit **one section (folder) per PR** rather than translating all pages at once — this keeps reviews manageable and allows incremental progress.
117+
118+
See [TRANSLATION.md](TRANSLATION.md) for technical details and TM format.
12119

13120
## How we collaborate
14121

@@ -32,4 +139,4 @@ Report security vulnerabilities through [GitHub Security Advisories](https://git
32139

33140
All contributors are expected to follow the **[Code of Conduct](https://github.com/kakao/actionbase/blob/main/CODE_OF_CONDUCT.md)**.
34141

35-
For project roles, see [Governance](https://actionbase.io/community/governance/).
142+
For project roles, see [Governance](GOVERNANCE.md).

website/src/content/docs/community/governance.mdx renamed to GOVERNANCE.md

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,13 @@
1-
---
2-
title: Governance
3-
description: Overview of Actionbase's governance model and roles
4-
sidebar:
5-
order: 2
6-
---
1+
# Governance
72

83
Actionbase is in its early open-source stage.
94
Our governance structure is transparent and flexible.
105

11-
For practical guidance on how to contribute — see [Contributing](/community/contributing/).
6+
For practical guidance on how to contribute — see [Contributing](CONTRIBUTING.md).
127

138
## Roles
149

15-
- **Maintainer**: Oversees project direction, ensures quality, and manages [releases](/community/releases/).
10+
- **Maintainer**: Oversees project direction, ensures quality, and manages [releases](RELEASES.md).
1611
Maintainers have final decision-making authority.
1712
Under the current governance model, Maintainers are Kakao employees.
1813

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ Early open-source preparation phase. The first release focuses on introducing co
107107

108108
## Contribute
109109

110-
We welcome contributions. See our [Contributing Guide](https://actionbase.io/community/contributing/).
110+
We welcome contributions. See our [Contributing Guide](CONTRIBUTING.md).
111111

112112
For questions, ideas, or feedback, join us on [GitHub Discussions](https://github.com/kakao/actionbase/discussions/).
113113

website/src/content/docs/community/releases.mdx renamed to RELEASES.md

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,4 @@
1-
---
2-
title: Release Policy
3-
description: Versioning scheme and support policy for Actionbase
4-
sidebar:
5-
order: 3
6-
---
1+
# Release Policy
72

83
Actionbase follows [Semantic Versioning](https://semver.org/) (SemVer) to communicate changes clearly.
94

‎TRANSLATION.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Translation
2+
3+
Actionbase documentation is translated using a **Translation Memory (TM)**
4+
workflow. English is the source language; translations are generated by
5+
applying exact-match TM lookups to the English MDX files.
6+
7+
Translation Memory (TM) is a key-value store that maps English source
8+
segments to their translations. Each document has its own TM file,
9+
managed at the document level.
10+
11+
## How it works
12+
13+
```
14+
en/*.mdx ──┐ ┌──────────────┐ ┌─────────────┐ ┌──────────┐
15+
├──▶│ Parse MDX │──▶│ TM Lookup │──▶│ Generate │──▶ {lang}/*.mdx
16+
tm/*.yaml ─┘ │ (segments) │ │ HIT→target │ │ output │
17+
└──────────────┘ │ MISS→source │ └──────────┘
18+
└─────────────┘
19+
```
20+
21+
The build command parses each English MDX into **segments** (title,
22+
description, headings, paragraphs, tables, list items). Each segment is
23+
looked up by exact string match — a **HIT** replaces the English text
24+
with the translation, and a **MISS** keeps the English text as-is.
25+
Non-translatable content (code blocks, imports, JSX, images) passes
26+
through unchanged.
27+
28+
Translated headings receive an explicit `{#english-slug}` anchor derived
29+
from the English source heading, ensuring cross-page links remain valid
30+
regardless of the translated heading text.
31+
32+
## TM format
33+
34+
Each document has a YAML file at `website/i18n/tm/{lang}/{doc-path}.yaml`:
35+
36+
```yaml
37+
meta:
38+
contributors:
39+
- alice # GitHub username of human contributor
40+
entries:
41+
- source: "Core Concepts"
42+
target: "Translated text"
43+
context: heading
44+
- source: "Actionbase is a database for serving user interactions."
45+
target: "Translated text for the paragraph"
46+
context: paragraph
47+
```
48+
49+
| Field | Description |
50+
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
51+
| `meta.contributors` | GitHub usernames of human contributors |
52+
| `entries[].source` | English text (exact match key) |
53+
| `entries[].target` | Translated text. Empty string (`""`) = untranslated |
54+
| `entries[].context` | Segment type: `frontmatter:title`, `frontmatter:description`, `heading`, `paragraph`, `table`, `list_item`, `summary`, `blockquote` |
55+
56+
## File structure
57+
58+
```
59+
website/i18n/
60+
tm/{lang}/{doc-path}.yaml # Translation Memory per document
61+
scripts/translation-memory.ts # TM tool
62+
website/src/content/docs/
63+
*.mdx # English source (authoritative)
64+
{lang}/*.mdx # Generated from TM — do not edit
65+
TRANSLATION.md # This file
66+
```
67+
68+
## CLI reference
69+
70+
All commands run from the `website/` directory. The `--lang` flag defaults
71+
to `ko` and can be changed to target other languages.
72+
73+
```bash
74+
npm run translate -- init # Create empty TM files for new EN docs
75+
npm run translate -- update # Sync TM with updated EN source
76+
npm run translate -- build # Rebuild translated docs from TM
77+
npm run translate -- validate # Validate TM without writing files
78+
npm run translate -- status # Translation coverage (table)
79+
npm run translate -- status --format=summary # Coverage (markdown)
80+
npm run translate -- --lang ko status # Target a specific language (default: ko)
81+
```
82+
83+
| Command | Purpose |
84+
| ---------- | ------------------------------------------------------------------------------------- |
85+
| `init` | Create empty TM entries for documents that have no TM file yet |
86+
| `update` | Add new segments (empty target), remove stale entries, preserve existing translations |
87+
| `build` | Generate `{lang}/*.mdx` from TM lookups |
88+
| `validate` | Dry-run build to catch YAML or segment errors |
89+
| `status` | Show per-document HIT/MISS counts and coverage percentage |
90+
91+
| Flag | Description |
92+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
93+
| `--lang` | Target language (default: `ko`) |
94+
| `--model` | LLM model identifier. When set and a document has no human contributors, `translated-by-{model}: true` is added to the output frontmatter. Useful for external workflows that auto-generate TM via LLM |
95+
96+
CI runs `validate` on pull requests and `build` on merge to main.
97+
98+
## Known limitations
99+
100+
- **Exact match only** — any change to an English segment requires
101+
updating the corresponding TM entry. Use `update` to detect new/stale
102+
segments automatically.
103+
- **Multi-line JSX components** (e.g., `<LinkCard>`) are passed through
104+
and may reformat slightly.

0 commit comments

Comments
 (0)