zhangshenghang opened a new pull request, #12347:
URL: https://github.com/apache/seatunnel/pull/12347
## Purpose of this PR
This PR fixes a batch of real documentation defects found by cross-checking
the docs against connector source code on `upstream/dev`, plus a link/anchor
and en-vs-zh consistency sweep. 33 documentation files are updated (33rd file
is a new zh translation), with English and Chinese kept in sync wherever the
same wrong content existed.
## What documentation issues were found
**Option defaults inconsistent with code (each verified against the actual
`Options.key(...)` definition):**
1. **File source connectors `field_delimiter`** – the docs claimed a
format-dependent default `\001 for text and , for csv`, but
`FileBaseSourceOptions.FIELD_DELIMITER` has a single default
`TextFormatConstant.SEPARATOR[0]` (= `\001`) for all formats, and several docs'
own descriptions already said "Default \`\\001\`, the same as hive's default
delimiter". Fixed in en
BosFile/CosFile/FtpFile/GcsFile/HdfsFile/LocalFile/OssJindoFile/S3File/SftpFile
and zh BosFile/GcsFile/OssJindoFile.
2. **JDBC `split.sample-sharding.threshold`** – Kingbase and PostgreSQL docs
(en + zh) listed the default as `10000`, while the code (`JdbcSourceOptions`)
and the base `Jdbc.md` doc both say `1000`, and the surrounding description
text itself says "The default value is 1000 shards". Fixed to `1000`.
3. **Doris sink `sink.enable-delete`** – default shown as `-` while
`DorisSinkOptions` defines `defaultValue(false)` (other boolean rows in the
same table show `false`). Fixed (en + zh).
4. **OneSignal `format`** – default shown as `json`, but the option inherits
`HttpSourceOptions.FORMAT` with `ResponseFormat.TEXT` default; the OneSignal
module never overrides it. Fixed to `text` (en + zh).
5. **FtpFile (en) `csv_use_header_line`** – default cell was empty while the
code default is `false` and every other file-connector doc (incl. zh FtpFile)
shows `false`. Fixed.
6. **Socket (en) `host`/`port`** – used `_` as the default-column marker;
normalized to `-` like all other docs (zh already used `-`).
**Malformed tables (content rendered invisible or in the wrong column):**
7. **Hive (zh) options table** – had only 4 columns while en has 5;
descriptions were crammed into the *default* column (e.g. "已废弃，请使用
tables_configs"). Rebuilt the table with the missing Description column,
translated from the en table.
8. **LocalFile (en + zh) `tables_configs` row** – 4-cell row with the
description sitting in the default column. Fixed to `-` default (the
description already exists in the `### tables_configs` section below the table).
9. **LocalFile (zh) `metalake_type` / `sort_files_by_modification_time`
rows** – phantom 5th cell with description text (not rendered by markdown).
Trimmed to match the table structure; preserved the `metalake_type` description
by adding a short `### metalake_type` section (en has no such section), and
`sort_files_by_modification_time` is already covered by its existing section.
10. **PostgreSQL (zh)** – table ended with a stray `|` line rendering as an
empty row, and the `common-options` row present in en was missing. Replaced the
stray line with the missing row.
**Broken links (404 on the published docs site):**
11. `docs/{en,zh}/faq.md`, `developer/how-to-create-your-connector.md`,
`developer/contribute-plugin.md`, `developer/contribute-transform-v2-guide.md`
(en + zh) linked to repo-root files (`../../seatunnel-connectors-v2/README.md`,
`../../../seatunnel-transforms-v2/README(.zh).md`) via relative paths that
resolve outside the Docusaurus docs root, so they 404 on seatunnel.apache.org.
Replaced with absolute `github.com/apache/seatunnel/blob/dev/...` links (the
convention already used in `developer/coding-guide.md`).
**Missing Chinese doc:**
12. The Splunk source connector (#12281) shipped with an English doc only.
Added `docs/zh/connectors/source/Splunk.md` (full translation) and the missing
`docs/zh/connectors/changelog/connector-http-splunk.md` it imports.
## Which areas/files were updated
- `docs/{en,zh}/connectors/source/*` – file connectors (BosFile, CosFile,
FtpFile, GcsFile, HdfsFile, LocalFile, OssJindoFile, S3File, SftpFile), Hive
(zh), Kingbase, PostgreSQL, OneSignal, Socket, Splunk (new zh doc)
- `docs/{en,zh}/connectors/sink/Doris.md`
- `docs/{en,zh}/faq.md` and `docs/{en,zh}/developer/*` – link fixes
- `docs/zh/connectors/changelog/connector-http-splunk.md` (new)
In total: **33 files changed, 121 insertions, 58 deletions**.
## Were both English and Chinese docs checked?
Yes. The sweep covered both `docs/en` and `docs/zh`; every fix above was
applied to both language versions wherever the same wrong content existed, and
en/zh option-table defaults were diffed connector-by-connector to catch drift
(e.g. en FtpFile `csv_use_header_line` vs zh).
## How duplicate PRs from the last 7 days were checked
`gh pr list --repo apache/seatunnel --state all --search
"created:>=2026-09-09"` was reviewed for all Docs-related PRs. Found: #12331
(my own open docs PR from yesterday), #12330 (AGENTS.md, unrelated), #12328
(IMap persistence examples, unrelated), #12276 (Http-Linear zh translation –
the `connector-v2/source/Http-Linear.md` gap it owns is not touched here). None
of the issues fixed in this PR overlap with #12331: that PR covers Kafka
`is_native`, Persistiq, HugeGraph/IoTDBv2 defaults, file **sink**
`field_delimiter` defaults, ObsFile/OssFile **source** option renaming, the zh
`connector-faq.md` anchors, edge-agent anchors and related anchor fixes — all
deliberately avoided here. The only shared *files* are
`docs/zh/connectors/source/{BosFile,OssJindoFile}.md`, where #12331 fixes
anchor lines and this PR fixes the `field_delimiter` table row (different
hunks, no conflict).
## How the change was verified
- Scripted link/anchor sweep over all `\*.md` under `docs/en` and `docs/zh`
(relative targets must exist; heading slugs + `<span id>` anchors, fenced code
blocks excluded): the 10 README-link breakages fixed here are resolved, and no
new broken links/anchors were introduced (remaining findings are exactly the
set already owned by open PR #12331).
- Scripted table-structure check on every modified file (consistent column
count per table block): 0 issues after the fix.
- Every changed default was manually verified against the connector source
(file paths and definitions cited above); no build/test run is needed since
this PR only touches Markdown files.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
