Search and Replace Image Alt Text in Microsoft Word
Question details
Replace English image alt-text descriptions with Spanish translations from an Excel mapping table and optionally clear alt-text titles.

- Product
- Microsoft Word and Microsoft Excel
- Device & OS
- not provided
- Scenario
- A user needs to translate hundreds of image descriptions in Word documents using a prepared list of translations.
- Observed behavior
- Word does not provide a simple built-in command to replace image alt text in bulk using an Excel translation table.
Prepare an Excel workbook with exact English descriptions in column A and Spanish translations in column B, starting in row 1. You need desktop Word with VBA enabled and Excel installed; confirm that clearing titles is appropriate for the document before running the macro.
Replace image descriptions with a Word VBA macro
Use an Excel mapping table to update matching inline and floating image descriptions and clear their titles.
The macro checks inline shapes and floating shapes in the main document story. It does not cover headers, footers, grouped shapes, or other content outside that scope.
Matches are exact and case-sensitive. Rows with a blank English description or translation are skipped; if an English description appears more than once, the last translation is used. Titles are cleared on all visited shapes, including those without a matching description.
In Excel, put each English description in column A and its Spanish translation in column B on the first worksheet. Do not include a header row. Save the workbook and note its full path.
Open the document in desktop Word, press Alt+F11, and choose Insert > Module. Paste the code below into the module, then replace the example workbook path with the full path to your Excel file: Sub TranslateImageAltText() Dim doc As Document, xl As Object, wb As Object, ws As Object Dim mapping As Object, obj As Object Dim lastRow As Long, r As Long, changed As Long, titleErrors As Long Dim key As String, translation As String, errorText As String Set doc = ActiveDocument On Error GoTo Failed Set mapping = CreateObject("Scripting.Dictionary") mapping.CompareMode = 0 Set xl = CreateObject("Excel.Application") Set wb = xl.Workbooks.Open("C:\path\to\translations.xlsx", ReadOnly:=True) Set ws = wb.Worksheets(1) lastRow = ws.Cells(ws.Rows.Count, 1).End(-4162).Row For r = 1 To lastRow key = CStr(ws.Cells(r, 1).Value) translation = CStr(ws.Cells(r, 2).Value) If Len(key) > 0 And Len(translation) > 0 Then mapping(key) = translation Next r For Each obj In doc.InlineShapes UpdateShapeAltText obj, mapping, changed, titleErrors Next obj For Each obj In doc.Shapes UpdateShapeAltText obj, mapping, changed, titleErrors Next obj GoTo CleanUp Failed: errorText = Err.Description CleanUp: On Error Resume Next If Not wb Is Nothing Then wb.Close SaveChanges:=False If Not xl Is Nothing Then xl.Quit On Error GoTo 0 If Len(errorText) > 0 Then MsgBox "Stopped: " & errorText & vbCrLf & "Some shapes may already have been updated." Else MsgBox changed & " descriptions updated. Titles could not be cleared on " & titleErrors & " shapes." End If End Sub Private Sub UpdateShapeAltText(ByVal obj As Object, ByVal mapping As Object, ByRef changed As Long, ByRef titleErrors As Long) Dim currentText As String currentText = obj.AlternativeText If mapping.Exists(currentText) Then obj.AlternativeText = mapping(currentText) changed = changed + 1 End If On Error Resume Next Err.Clear obj.Title = "" If Err.Number <> 0 Then titleErrors = titleErrors + 1 Err.Clear On Error GoTo 0 End Sub
Return to Word, select Developer > Macros, choose TranslateImageAltText, and click Run. Review the completion message and inspect representative images using their Alt Text options, then save the document.
To reuse the macro, save it in a Word macro-enabled template (.dotm) in Word's Startup folder. Check the Startup location under File > Options > Advanced > File Locations, restart Word, and run the macro with each target document active.

Work with Word documents and translation tables in WPS Office
WPS Office is a free, lightweight alternative with a familiar interface for working with documents and spreadsheets. Open existing Office files to make migration straightforward; the Microsoft Word VBA automation described above requires Word and Excel.

Frequently Asked Questions
Will the macro translate descriptions that are not in the Excel table?
No. It replaces only exact, case-sensitive matches from column A with the corresponding text in column B. Add missing descriptions and translations to the first worksheet before running it.
Does the macro clear titles on images without a translation?
Yes. It attempts to clear the Title property on every inline or floating shape it visits, even if its description has no match. The completion message reports how many title-clearing attempts failed.
Will the macro update images in headers and footers?
No. This example processes shapes in the main document story only. Images in headers, footers, grouped shapes, and other locations require separate handling or manual review.
Where should I store the macro for reuse?
Save it in a macro-enabled .dotm template in Word's Startup folder. Find the configured location under File > Options > Advanced > File Locations, and use macros only from trusted sources.




