Encoding Rules

Fix garbled text in VS Code: set encoding rules once per folder or path pattern

Seeing � or é in your files? VS Code can't always detect legacy encodings (Windows-1252, Windows-1257, Shift-JIS, GBK…), so text ends up garbled.

Encoding Rules lets you assign an encoding to a file, folder or glob pattern. Set it once, and the file opens correctly every time, with no more File → Reopen with Encoding.

Ideal for legacy codebases, imported files, and repositories that mix UTF-8 with older encodings.

Quick Start

1. Open a file that shows garbled text.
2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Encoding Rules: Create Rule for Current Folder (or ...for Current File).
3. Pick the encoding. From now on, matching files open with it.

Why not just use VS Code's auto-detection?

VS Code can guess encodings (files.autoGuessEncoding), but it's a statistical guess: it can pick the wrong encoding, and the list of encodings you can prioritize with files.candidateGuessEncodings doesn't include every encoding.

Encoding Rules takes a different approach: you decide once, and it's applied every time, for any encoding VS Code can open.

Features

• Applies your chosen encoding automatically whenever a matching file is opened.
• Matches by file path using glob patterns: a single file, a folder, or a whole tree.
• Keeps a legacy folder in, say, Windows-1257 while the rest of your repo stays UTF-8.
• Resolves overlapping rules predictably: the most specific rule wins.
• Shows a status bar indicator, so you can see how a rule relates to the current file and fix it in one click.
• Stores rules in a regular VS Code setting (encodingRules.rules), so you can also edit them by hand.

Commands

Encoding Rules provides the following commands through the VS Code Command Palette.

Open the Command Palette with Ctrl+Shift+P (Cmd+Shift+P on macOS) and search for Encoding Rules.

Status Bar Indicator

An Encoding Rule item appears in the status bar, near VS Code's own encoding indicator, whenever it has something useful to tell you about the active file.

Found the right encoding with Reopen with Encoding? Click + Encoding Rule to keep it as a rule.

Use the encodingRules.statusBar setting to show the indicator for every file (always) or hide it (never).

Configuration

Add encoding rules in your VS Code settings:

{
  "encodingRules.rules": {
    "windows1257": [
      "**/legacy/**"
    ],
    "shiftjis": [
      "**/jp-import/**"
    ]
  }
}

The setting is an object where:

In the example above, files in legacy open as Windows-1257, and files in jp-import open as Shift-JIS.

Rule priority

If more than one rule matches a file, the most specific rule wins: the matching pattern with the most characters takes priority, regardless of the order in your settings.

For example, if you also had a rule for **/*.txt, the file legacy/notes.txt would still open as Windows-1257, because **/legacy/** is the longer pattern. To make a rule win over another, make its pattern more specific.

Pattern matching is case-insensitive, and Windows-style backslashes in paths are handled automatically. Not sure which rule applies to a file? Run Encoding Rules: Show Matching Rule.

Other settings

Lowering encodingRules.maxFileSize is useful if you want to skip large files that are slow to reopen. Raising it above about 50 MB may have no effect, because VS Code may not make very large files available to extensions.

Supported Encodings

Supported encodings depend on VS Code's built-in encoding support. Use VS Code's encoding IDs (for example windows1252, not windows-1252). The Create Rule commands let you pick from a list, so you don't have to memorize them.

Common examples:

Glob Patterns

Rules use glob patterns to match files.

Known Limitations

• Encoding detection is not performed. Rules are based on file paths.
• Incorrect rules may cause files to be opened with the wrong encoding.
• Some VS Code internal documents may not have normal file paths.
• The extension does not modify file contents; it only controls how files are opened.
• If you manually choose Reopen with Encoding, VS Code keeps that choice until the file is closed. The next time the file opens, your rule applies again.
• Large files are skipped. The default limit is 50 MB, and you can lower it with encodingRules.maxFileSize.

Support

If Encoding Rules saves you time, consider supporting development:

License

MIT License