Originally published at: macOS Text Replacement Export/Import Works Great Until It Doesn’t - TidBITS
Does everyone reading this know that Apple has long provided basic text expansion capabilities in macOS, iOS, and iPadOS? You’ll find them in System Settings > Keyboard > Text Replacements on the Mac; in iOS and iPadOS, go to Settings > General > Keyboard > Text Replacement. In each, a text replacement consists of a shortcut and a replacement phrase. Type the shortcut, followed by a space or a punctuation character, and its phrase will replace it.
Text expansion is a great way to speed up typing of email addresses, frequently used URLs, emoji and special characters, hard-to-type words, complex Unix commands, and chunks of boilerplate text. It’s also excellent for automatically fixing common typos—if you regularly type “teh” instead of “the,” a text replacement can fix your finger fumbles.
What I didn’t know until recently is that Apple provides a hidden—but documented, amazingly!—way to export your replacement pairs to a property list file. All you have to do is select the items to export (Command-A selects all) and drag them to the desktop. You can then edit that file in a text editor like BBEdit or TextEdit before reimporting it, which is merely a matter of dragging it back into the Text Replacements dialog. This export/import feature is useful in three ways:
- Backup: If you have an extensive set of text replacements, making a backup would be a sensible precaution.
- Sharing: Any Mac user can import your text replacements, so if you’ve built up a custom collection of scientific, medical, or technical replacements, you can share them with colleagues.
- Easier editing: Bulk changes might be easier to make outside Apple’s one-at-a-time interface.
The TidBITS AutoCorrect Dictionary
Once I realized I could import text replacement pairs, I had another thought. If you had a large list of typos and the correct versions of their associated words set up as text replacements, you’d likely end up with many fewer typing mistakes in your documents.
Where would you acquire such a list of typos? Over 25 years ago, for the MacHack developers conference, I created the public domain TidBITS AutoCorrect Dictionary, based in large part on a word list from then-Princeton student Micah Alpern (see “An ATypoKill Eudora Hack,” 4 September 2000). It contains over 2700 pairs of misspelled or miscapitalized words and their correct replacements.
Years later, it was integrated into Typinator (see “TidBITS AutoCorrect Dictionary Enhances Typinator,” 27 August 2007), TextExpander, and TypeIt4Me (see “TidBITS AutoCorrect Dictionary for TextExpander and TypeIt4Me,” 10 September 2007).
Several years after that, Apple added text replacement capabilities to Mac OS X 10.6 Snow Leopard. Longtime TidBITS Talk contributor Lewis Butler wrote an article about how to integrate the TidBITS AutoCorrect Dictionary in “Improve Snow Leopard’s Autocorrection Capabilities” (16 September 2009). (Sadly, Lewis died unexpectedly in January 2022.) He discovered that Apple stored the text replacement list in an invisible file at ~/Library/Preferences/.GlobalPreferences.plist and then figured out how to convert the TidBITS AutoCorrect Dictionary to use the appropriate data structure. It worked, but required a complicated manual integration process.
A Rabbit Hole of Twisty Little Passages, All Different
I was all ready to give you an updated version of the TidBITS AutoCorrect Dictionary that could be imported into the Text Replacements dialog, but after hours of testing, I just couldn’t make it work reliably enough. Some of the problems I encountered included:
- An unhelpful error dialog appeared when importing a file containing “too many” entries, though I never figured out what “too many” meant. In some cases, I could dismiss it and see the replacements. In others, I had to force quit System Settings and start over.
- Sometimes, after an import, most or all of the imported entries would appear. Other times, the Text Replacements list was zeroed out. In one early test, when the imported entries did appear, I exported them, cleared the list, and reimported, only to get the error again. So an export/import pass didn’t fix the file.
- Sometimes, the Text Replacements dialog wouldn’t accept a dropped file for import on the first try but would on a subsequent try. Quitting and relaunching System Settings sometimes made a difference, but not always. Restarting might have helped, but it’s also possible that iCloud syncing was getting in the way.
- A binary search approach (splitting the file in half and halving it again) didn’t identify any corrupted entries, nor did removing a few entries that Claude and ChatGPT agreed were iffy because they contained double quotes. Sorting all the entries alphabetically made no difference. Splitting the file into smaller pieces sometimes worked, but a file containing 1000 entries imported unpredictably. Imports usually (always?) worked with files containing just 100 entries, but I don’t know if they would have failed when the total number exceeded some threshold.
- iCloud syncing seems to have thrown up its hands at some point, so although I was able to delete all the failed tests from both of my main Macs and reimport my original handful of text replacements, my iPhone still contains the full set from one of the early imports that worked but crashed System Settings. I don’t know if they’ll all catch up with each other eventually.
- I tried adding my entries to the invisible
.GlobalPreferences.plistfile, but macOS silently deleted them as soon as I opened the Text Replacements dialog.
In short, I give up. But in the interest of science, where negative results can still advance the field, I’m making my reformatted and ready-to-import TidBITS AutoCorrect Dictionary available for download again. I suspect Apple never tested its import or syncing code with a file containing so many entries, but someone else may be able to devise a workaround that addresses the limitations without being too onerous. If you figure out a reliable method, let us know in the comments.
Of course, the easiest and most reliable workaround is to stick with TextExpander, Typinator, or TypeIt4Me, all of which properly handle very large numbers of replacements and already include the TidBITS AutoCorrect Dictionary. This is why we have independent developers!
