Photo Mechanic’s code replacement speeds up captioning of often-used terms or names like those used in sports photography but can be used to make a shorthand for caption replacements in any type of photography.

To use code replacement, create a plain (UTF-8) text file with two or more tab-separated columns. Some spreadsheet programs call this a "Tab-Delimited text" file and some call it "Tab-separated values." The first column is the “code” and the second (or more) are the replacements. 

 Here’s a sample code replacement for a fictional game featuring the Chattanooga Choo-Choos and the Detroit Dunkers: 

CC2     Aaron Barnum
CC8 Daren Bram
CC11 Dain Green
CC13 Dennis George
CC17 Rick Perkins
CC43 Brian Calloway
DD13 Victor Zenfliende
DD14 Ken Pierce
DD43 Paul Kroyd
DD44 Brian Scoletto
DD55 Wally Flannenbaum
⚠️Warning: you must use the tab key to separate your columns. Spaces will not work.  

Keep your codes short and unique. In this example, each team name is abbreviated with two letters and one or two numbers that match the player’s jersey number. Some of the player’s names are difficult to spell correctly, even if you are familiar with them. By using code replacement, you only have to remember the correct spelling once.

Tip: Codes are case-sensitive. Save time with code replacement by using lower case codes to save the extra keystrokes as you type. We're using capital letters here for visual contrast.

Setting code replacements

Once you have created your text file, go to Edit > Settings > Set Code Replacements.
This is where you can define which files contain code replacement data. If there are multiple code replacements, the most recently uploaded file will be used.
The “delimiter” field is the keyboard character you will use to tell Photo Mechanic to do a Code Replacement. The default character is =, but you may change it.
Example: you have a picture with two players, and you can visibly see their jersey numbers in the thumbnail preview of the Metadata (IPTC) Info. You just type in your codes for each player, surrounded by the = character (or your delimiter if you have changed it).

Multiple code replacements

You can have multiple replacements for a single code. Use a tab character after each replacement. Example:

code    replacement    replacement #2    replacement #3


ff   staff   Jane Smith    Wilson Oluo 

By default, your standard replacement will be the first one. In order to substitute the alternates instead of the first code replacement, you need to add the field selector (the pound sign ‘#’) followed by the number of the replacement you want to select. In this example,  =ff= replaces with "staff" and  =ff#2=  replaces with "Jane Smith," and =ff#3= replaces with "Wilson Oluo." 

Code Replacement with Variables

Code replacements can be combined with variables.  For example,  if you wanted to use the variable {monthname} but you wanted it to be translated to a different language from English, say Spanish, you could create a code replacement file that looks like this: (Note: in your file, there should be one tab character between items in each column, not spaces.)

January        Enero
February     Febrero
March        Marzo
April        Abril
May      Mayo
June         Junio
July         Julio
August        Agosto
September     Septiembre
October        Octubre
November     Noviembre
December     Diciembre

So if you now use ={monthname}= and the current month in English would be July then the Spanish replacement would become Julio.
You can also combine frequently used variable combinations to save time.
If you often used the set of variables {day} {monthname} {year4} in your captions you could create an entry in your code replacement file that looks like this:

mydate {day} {monthname} {year4}

You could then just type: =mydate= and your photo’s date information would be replaced. Code replacement can be used as a macro for any list of terms you enter commonly. Code Replacement also works in every text field of the Metadata (IPTC) Info and Metadata (IPTC) Template windows.


You can use hidden comments in your plain text replacement code in order to help you track your replacements or work with teams. Comments must either start at the beginning of a line or be the last column on a line. Comments start with two forward slashes  //.

// this is a comment for the whole line


code    replacement    // this is a comment for the rest of the line