Practical guide
SGF Comments Look Garbled: Check CA and the File Bytes
If an SGF comment looks garbled, check both the CA declaration and the saved bytes. CA tells a reader how to decode text; it does not convert the file. Work from a preserved original and a known intended comment before changing either part.
Preserve the original before trying a repair
Make a byte-for-byte copy of the SGF first. Record which application exported it, which application displayed the problem, and whether a particular comment has a known correct original. Repeatedly opening and saving a garbled display can turn an interpretation problem into permanently changed text.
Start with a small, identifiable comment rather than a whole game history. If the move tree still opens but Chinese text is wrong, that suggests a text-decoding problem; it does not prove that the moves, branches or board size are intact. Compare those separately after any repair.
In FF4, CA is a root property whose value identifies the character encoding. Without CA, the stated default is ISO-8859-1, also called Latin-1. A missing declaration does not establish that an unknown exporter actually wrote Latin-1. [1] [2]
A declaration and a conversion do different jobs
Text and SimpleText values use the declared encoding. Property identifiers and the other value types use ASCII. Thus a file can contain readable FF[4]GM[1] and coordinates while its comment is misinterpreted. C is Text. [1] [3]
On a narrow screen, scroll the comparison sideways. Keyboard users can focus the table and use the arrow keys.
| Operation | What changes | What it cannot establish |
|---|---|---|
| Edit CA | The encoding label inside the root node | That the existing bytes match the new label |
| Transcode text | Decode using a known source encoding, then encode in the chosen destination encoding | The original wording when the source encoding or text is unknown |
| Resave a garbled display | Potentially the already misinterpreted characters and their bytes | Recovery of the original intended comment |
Do not globally replace non-ASCII bytes or punctuation across the file. Preserve the SGF structure, escapes, node boundaries, unknown properties and game metadata. A text editor’s encoding choice and the file’s CA property must agree when you save the repaired copy.
One Chinese comment, two interpretations
(;FF[4]GM[1]CA[UTF-8]C[黑棋])In this original example, the known intended comment is 黑棋. Its UTF-8 bytes are e9 bb 91 e6 a3 8b, and the decoded Unicode characters are U+9ED1 U+68CB. The correctly declared sample preserves both.
Download the correctly declared Chinese comment. Keep your own record unchanged; these are original teaching examples.
The diagnostic counterpart keeps those same six comment bytes but declares ISO-8859-1. Interpreting them as Latin-1 produces six code points: U+00E9 U+00BB U+0091 U+00E6 U+00A3 U+008B. Some are control characters, so copying their visual appearance is a poor diagnosis. The bytes and the known original provide the useful comparison.
Deliberately faulty diagnostic file: Download the intentionally mismatched CA example. Keep your own record unchanged; these are original teaching examples.
Latin-1 can decode these bytes without a decoding exception. Successful decoding therefore does not mean the resulting text is the intended Chinese comment. Here, changing the declaration to UTF-8 fits the known original bytes; that conclusion belongs to this example, not every garbled file.
Why relabeling café does not convert it
Our second source sample is Latin-1 and contains café. The final character is the single byte e9. The valid Latin-1 sample declares ISO-8859-1. A deliberately relabeled version declares UTF-8 while retaining that byte; decoding its comment as UTF-8 raises a UnicodeDecodeError in the verification used here.
Download the valid Latin-1 café sample. Keep your own record unchanged; these are original teaching examples.
Deliberately faulty diagnostic file: Download the unchanged Latin-1 bytes with a wrong UTF-8 label. Keep your own record unchanged; these are original teaching examples.
A proper conversion first decodes the known Latin-1 text, then writes UTF-8. The é becomes the two bytes c3 a9, and CA is set to UTF-8. The destination still reads café; its bytes are different because an actual conversion happened.
Download the actually transcoded UTF-8 café sample. Keep your own record unchanged; these are original teaching examples.
These examples were checked with sgfmill 1.1.1 for grammar and exact decoded text or the expected error. That is a file-level check, not a demonstration of importing and exporting in your particular viewer.
A careful repair sequence
- Keep the untouched original and work on a copy. Find an intended comment from the exporter, author or another trustworthy copy.
- Inspect the existing CA and the editor’s current byte interpretation. Avoid saving until you know which encoding matches the original bytes.
- If only CA is wrong, correct that declaration while preserving the known correct bytes. If changing encodings, decode from the established source encoding and actually re-encode.
- Save with the destination encoding and a matching CA. Reopen the copy and compare several comments, names and accents against their known originals.
- Compare the root size, setup stones, moves, branches and metadata with the original. Keep the repair notes and both files.
When the source encoding remains unknown, do not publish a confident repaired record. Obtain the original export or ask the record’s author for a known text fragment. Guessing from one readable word can miss damage elsewhere.
Two decisions to practise
Chinese text is wrong, but its known UTF-8 bytes are unchanged. Must I rewrite the comment?
Correct the mismatched declaration in a copy; preserve the known correct bytes.
Use the Chinese sample above as the comparison. Its six bytes already encode the intended two characters. After correcting CA, reopen and verify the text and record structure. If your own file’s bytes differ or the original is unknown, this conclusion does not automatically apply.
A Latin-1 café comment fails after I change CA to UTF-8. Should I keep trying different labels?
Restore the original copy and perform a real conversion from the known source encoding.
The single e9 byte has not become the UTF-8 sequence c3 a9 merely because CA changed. Decode the established Latin-1 text, write UTF-8, align the label, and verify the result. Keep an unresolved file unchanged when the original encoding cannot be established.
If only part of a correct comment disappears
Once the text decodes correctly, an unexplained missing bracket or backslash is a different file question. Check comment escaping before treating it as another encoding problem. A literal closing bracket needs an SGF escape even in a correctly encoded UTF-8 file.
Keep the difference between the source file and its presentation visible: the text you know, the bytes you saved, the CA you declared, and what your chosen application displays. Those four observations make a useful troubleshooting report.
Sources and further reading
- SGF FF4: file format specificationText escaping, property scope and compressed point-list rules.
- SGF FF4: CA propertyDeclared character encoding and its default.
- SGF FF4: C propertyComments use the Text value type.