Standardize FormosanBank MT model card format

README.md

@@ -70,16 +70,14 @@ model-index:
 
 **Repo:** `FormosanBank/nllb200-formosan-zh-spm8k`  
 **Base model:** [`facebook/nllb-200-distilled-600M`](https://huggingface.co/facebook/nllb-200-distilled-600M)  
-**Direction:** **Formosan -> Traditional Chinese** (`zho_Hant`)  
+**Direction:** **Formosan -> Traditional Chinese**  
 **Companion reverse-direction model:** [`FormosanBank/nllb200-zh-formosan-spm8k`](https://huggingface.co/FormosanBank/nllb200-zh-formosan-spm8k)
 
-This model is an NLLB-200 distilled 600M checkpoint adapted for machine translation from 15 Formosan languages into Traditional Chinese using an 8k SentencePiece vocabulary extension and FormosanBank control tags.
+This is a directional NLLB-200 distilled 600M checkpoint for FormosanBank machine translation. It uses an 8k SentencePiece vocabulary extension plus FormosanBank metadata/control tags. Use the companion model for the reverse direction.
 
-This is a directional checkpoint. It is trained for this direction only; use the companion model for Chinese -> Formosan.
+## Supported Languages
 
-## Languages
-
-| Language | Code |
+| Language | NLLB code |
 |---|---|
 | Traditional Chinese | `zho_Hant` |
 | Amis | `ami_Latn` |
@@ -100,11 +98,11 @@ This is a directional checkpoint. It is trained for this direction only; use the
 
 ## Input Format
 
-This model was trained and evaluated with metadata control tags. Prefix the source text with:
+This model was trained and evaluated with metadata control tags. Prefix the source text in one of the supported Formosan languages with:
 
 `<to_zh> <src_LANG> <dom_BUCKET> <dialect_DIALECT>`
 
-For example, Amis input with unknown metadata should use:
+Example with unknown metadata:
 
 `<to_zh> <src_ami> <dom_unknown> <dialect_default> Pa'araw cingra to demak nira.`
 
@@ -112,9 +110,9 @@ If source bucket or dialect is unknown, use `<dom_unknown>` and `<dialect_defaul
 
 ## Usage
 
-Tested with `transformers` 4.56.x. For NLLB generation, keep `decoder_start_token_id=tokenizer.eos_token_id` and set `forced_bos_token_id` to the target language ID.
+Tested with `transformers` 4.56.x. Use the slow `NllbTokenizer` or `AutoTokenizer.from_pretrained(model_id, use_fast=False)`. In `transformers` 4.56.x, fast-tokenizer added-token IDs can differ from the slow tokenizer IDs used during training.
 
-**Tokenizer note:** use the slow `NllbTokenizer` or `AutoTokenizer.from_pretrained(model_id, use_fast=False)`. In `transformers` 4.56.x the fast tokenizer can assign shifted IDs to added control tags, while training used the slow tokenizer IDs.
+For NLLB generation, keep `decoder_start_token_id=tokenizer.eos_token_id` and set `forced_bos_token_id` to the target language ID.
 
 ```python
 import torch
@@ -132,12 +130,7 @@ FORMOSAN_TO_LID = {
     "tsu": "tsu_Latn", "xnb": "xnb_Latn", "xsy": "xsy_Latn",
 }
 
-def translate_formosan_to_chinese(
-    text: str,
-    lang_code: str,
-    source_bucket: str = "unknown",
-    dialect: str = "default",
-) -> str:
+def translate_formosan_to_chinese(text: str, lang_code: str, source_bucket: str = "unknown", dialect: str = "default") -> str:
     tokenizer.src_lang = FORMOSAN_TO_LID[lang_code]
     prompt = f"<to_zh> <src_{lang_code}> <dom_{source_bucket}> <dialect_{dialect}> {text}"
     inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=384).to(model.device)
@@ -161,7 +154,7 @@ print(translate_formosan_to_chinese("Pa'araw cingra to demak nira.", "ami"))
 
 | Setting | Value |
 |---|---|
-| Corpus | FormosanBank Chinese Parallel Corpus, leakage-controlled `in_domain_hard` split |
+| Corpus | FormosanBank Chinese Parallel Corpus, leakage-controlled in-domain hard split |
 | Direction | `f2zh` |
 | Base model | `facebook/nllb-200-distilled-600M` |
 | Tokenizer | 8k Formosan SentencePiece extension |
@@ -178,13 +171,11 @@ print(translate_formosan_to_chinese("Pa'araw cingra to demak nira.", "ami"))
 | Language sampling alpha | 0.5 |
 | Metadata tags | enabled and validated as single tokenizer IDs |
 
-The final checkpoint is published because it scored higher than the best-by-validation-loss checkpoint on the held-out hard test set.
+This repo publishes the final 300k-step checkpoint because it scored highest on the held-out hard test set among the evaluated final/best checkpoints.
 
 ## Evaluation
 
-Evaluation was run on the held-out `in_domain_hard` test split with no normalized source/target/pair overlap against train. These scores are intentionally lower than leaky or near-duplicate splits and are meant to be a harder benchmark.
-
-SacreBLEU used Chinese tokenization (`tokenize=zh`) for BLEU in this direction.
+Evaluation used the held-out `in_domain_hard` test split with no normalized source, target, or pair overlap against train. These scores are intentionally lower than leaky or near-duplicate splits and are intended as a harder MT benchmark.
 
 ### Global Metrics
 
@@ -212,18 +203,19 @@ SacreBLEU used Chinese tokenization (`tokenize=zh`) for BLEU in this direction.
 | Kanakanavu | `xnb_Latn` | 1,552 | 12.96 | 15.19 | 107.91 |
 | Saisiyat | `xsy_Latn` | 1,212 | 14.45 | 16.32 | 106.80 |
 
-The raw evaluation metrics are included in [`eval/metrics.json`](eval/metrics.json), including source-bucket and length-bin breakdowns.
+Full source-bucket and length-bin breakdowns are available in [`eval/metrics.json`](eval/metrics.json).
 
 ## Intended Use
 
 - Research, teaching, and prototyping for Formosan-language MT.
-- Draft translation assistance where human review by knowledgeable speakers is available.
+- Draft translation assistance where review by knowledgeable speakers is available.
 - Comparative evaluation of low-resource MT methods on leakage-controlled FormosanBank splits.
 
 ## Limitations
 
 - Outputs can be incorrect, ungrammatical, incomplete, or culturally inappropriate.
-- The model is not suitable for legal, medical, safety-critical, or authoritative community-facing use without expert review.
+- Generation into Formosan languages is especially difficult and should be treated as draft-only.
+- This model is not suitable for legal, medical, safety-critical, or authoritative community-facing use without expert review.
 - Evaluation uses a hard split; BLEU should not be compared directly to older leaky or near-duplicate split results.
 
 ## License
@@ -233,10 +225,10 @@ Released under `cc-by-nc-4.0`. Some underlying corpus sources may carry addition
 ## Citation
 
 ```bibtex
-@misc{formosanbank_nllb200_spm8k_f2zh,
-  title  = {nllb200-formosan-zh-spm8k: Directional NLLB-200 MT for FormosanBank Chinese Parallel Corpus},
+@misc{formosanbank_nllb200_formosan_zh_spm8k,
+  title  = {nllb200-formosan-zh-spm8k: Directional NLLB-200 MT for the FormosanBank Chinese Parallel Corpus, leakage-controlled in-domain hard split},
   author = {FormosanBank contributors},
   year   = {2026},
-  howpublished = {\url{https://huggingface.co/FormosanBank/nllb200-formosan-zh-spm8k}}
+  url    = {https://huggingface.co/FormosanBank/nllb200-formosan-zh-spm8k}
 }
 ```