Python bindings around Google Chromium's embedded compact language detection library (CLD2)





GitHub Stars



Last Commit

13d ago










PYCLD2 - Python Bindings to CLD2

Python bindings for the Compact Langauge Detect 2 (CLD2).

Downloads Latest version Supported Python versions Development Status Download format Build status

This package contains forks of:

The goal of this project is to consolidate the upstream library with its bindings, so the user can pip install one package instead of two.

The LICENSE is the same as Chromium's LICENSE and is included in the LICENSE file for reference.


$ python -m pip install -U pycld2


import pycld2 as cld2

isReliable, textBytesFound, details = cld2.detect(
    "а неправильный формат идентификатора дн назад"

# True
# ('RUSSIAN', 'ru', 98, 404.0)

fr_en_Latn = """\
France is the largest country in Western Europe and the third-largest in Europe as a whole.
A accès aux chiens et aux frontaux qui lui ont été il peut consulter et modifier ses collections
et exporter Cet article concerne le pays européen aujourd’hui appelé République française.
Pour d’autres usages du nom France, Pour une aide rapide et effective, veuiller trouver votre aide
dans le menu ci-dessus.
Motoring events began soon after the construction of the first successful gasoline-fueled automobiles.
The quick brown fox jumped over the lazy dog."""

isReliable, textBytesFound, details, vectors = cld2.detect(
    fr_en_Latn, returnVectors=True
# ((0, 94, 'ENGLISH', 'en'), (94, 329, 'FRENCH', 'fr'), (423, 139, 'ENGLISH', 'en'))


This package exports one function, detect(). See help(detect) for the full docstring.

The first parameter (utf8Bytes) is the text for which you want to detect language.

utf8Bytes may be either:

  • str (example: "¼ cup of flour")
  • bytes that have been encoded using UTF-8 (example: "¼ cup of flour".encode("utf-8"))

Bytes that are not UTF-8 encoded will raise a pycld2.error. For example, passing b"\xbc cup of flour" (which is "¼ cup of flour".encode("latin-1")) will raise.

All other parameters are optional:

utf8Bytesstr or bytes*The text to detect language for.
isPlainTextbool, default FalseIf False, then the input is HTML and CLD will skip HTML tags, expand HTML entities, detect HTML <lang ...> tags, etc.
hintTopLevelDomainstrE.g., 'id' boosts Indonesian.
hintLanguagestrE.g., 'ITALIAN' or 'it' boosts Italian; see cld.LANGUAGES for all known languages.
hintLanguageHTTPHeadersstrE.g., 'mi,en' boosts Maori and English.
hintEncodingstrE.g, 'SJS' boosts Japanese; see cld.ENCODINGS for all known encodings.
returnVectorsbool, default FalseIf True, then the vectors indicating which language was detected in which byte range are returned in addition to details. The vectors are a sequence of (bytesOffset, bytesLength, languageName, languageCode), in order. bytesOffset is the start of the vector, bytesLength is the length of the vector. Note that there is some added CPU cost if this is True. (Approx. 2x performance hit.)
debugScoreAsQuadsbool, default FalseNormally, several languages are detected solely by their Unicode script. Combined with appropritate lookup tables, this flag forces them instead to be detected via quadgrams. This can be a useful refinement when looking for meaningful text in these languages, instead of just character sets. The default tables do not support this use.
debugHTMLbool, default FalseFor each detection call, write an HTML file to stderr, showing the text chunks and their detected languages. See cld2/docs/InterpretingCLD2UnitTestOutput.pdf to interpret this output.
debugCRbool, default FalseIn that HTML file, force a new line for each chunk.
debugVerbosebool, default FalseIn that HTML file, show every lookup entry.
debugQuietbool, default FalseIn that HTML file, suppress most of the output detail.
debugEchobool, default FalseEcho every input buffer to stderr.
bestEffortbool, default FalseIf True, then allow low-quality results for short text, rather than forcing the result to "UNKNOWN_LANGUAGE". This may be of use for those desiring approximate results on short input text, but there is no claim that these result are very good.

*If bytes, must be UTF-8 encoded bytes.


This package exports these global constants:

pycld2.ENCODINGSlist of the encoding names CLD recognizes (if you provide hintEncoding, it must be one of these names).
pycld2.LANGUAGESlist of languages and their codes (if you provide hintLanguageCode, it must be one of the codes from these codes).
pycld2.EXTERNAL_LANGUAGESlist of external languages and their codes.
pycld2.DETECTED_LANGUAGESlist of all detectable languages.

What About CLD3?

Python bindings for CLD3 are available over here gcld3.

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0
No reviews found
Be the first to rate


No alternatives found


No tutorials found
Add a tutorial