hankcs/HanLP · error · NotImplementedError

No translation for {lang}. Please contribute to our translat

Error message

No translation for {lang}. Please contribute to our translation at https://github.com/hankcs/HanLP

What it means

Document.translate only has localized templates for Chinese ('zh'); requesting any other language raises NotImplementedError asking for community contributions.

Source

Thrown at plugins/hanlp_common/hanlp_common/document.py:456

        .. Attention:: Note that the translated document might not print well in terminal due to non-ASCII characters.

        Args:
            lang: Target language to be translated to.
            tok: Token key.
            pos: Part-of-speech key.
            dep: Dependency parse tree key.
            sdp: Semantic dependency tree/graph key. SDP visualization has not been implemented yet.
            ner: Named entity key.
            srl: Semantic role labeling key.

        Returns:
            The translated document.

        """
        if lang == 'zh':
            from hanlp.utils.lang.zh import localization
        else:
            raise NotImplementedError(f'No translation for {lang}. '
                                      f'Please contribute to our translation at https://github.com/hankcs/HanLP')
        flat = isinstance(self[tok][0], str)
        for task, name in zip(['pos', 'ner', 'dep', 'sdp', 'srl'], [pos, ner, dep, sdp, srl]):
            annotations = self.get(name, None)
            if not annotations:
                continue
            if flat:
                annotations = [annotations]
            translate: dict = getattr(localization, name, None)
            if not translate:
                continue
            for anno_per_sent in annotations:
                for i, v in enumerate(anno_per_sent):
                    if task == 'ner' or task == 'dep':
                        v[1] = translate.get(v[1], v[1])
                    else:
                        anno_per_sent[i] = translate.get(v, v)
        return self

View on GitHub (pinned to ddb1299bdd)

Solutions

Call translate('zh') (or omit lang) to get the Chinese translation
Fork/contribute a localization module under hanlp.utils.lang.<lang> as the message suggests
Render the document without translation (to_markdown/pretty print uses raw field names)

Example fix

# before
doc.translate('en')  # NotImplementedError
# after
doc.translate('zh')

Defensive patterns

Strategy: try-catch

Validate before calling

SUPPORTED_TRANSLATE = {'zh'}
if lang not in SUPPORTED_TRANSLATE:
    lang = 'zh'

Type guard

def translate_supported(lang: str) -> bool:
    return lang == 'zh'

Try / catch

try:
    doc.translate(lang)
except NotImplementedError:
    doc.translate('zh')

Prevention

Only 'zh' is supported; don't expose lang switches to users without a whitelist

When it happens

Trigger: Calling doc.translate('en'), doc.translate(lang='ja'), or any lang != 'zh' on a Document object produced by HanLP parsing.

Common situations: Non-Chinese-speaking users wanting English output of pretty-printed annotations; passing a language code the API gives no hint about supporting.

Related errors

AI-assisted analysis of hankcs/HanLP@ddb1299bdd (2026-08-27). Data as JSON: /api/errors/7be23e912c08153d. Report an issue: GitHub.