VBA & Macro Problems

Search and Replace Image Alt Text in Microsoft Word

Muhammad TalhaMuhammad Talha Nov 13, 2026 868 views

Question details

Replace English image alt-text descriptions with Spanish translations from an Excel mapping table and optionally clear alt-text titles.

Search and Replace Image Alt Text in Microsoft Word
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.
Before you start

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.

Solution 1Recommended

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.

1
Create the mapping workbook

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.

2
Add the macro in Word

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

3
Run and review

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.

4
Make the macro available for other documents

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.

Replace image descriptions with a Word VBA macro
Check accessibility results: Some object types may not allow the title to be cleared. The macro reports those cases; inspect them manually and use Word's accessibility checks. Clearing titles alone does not guarantee Section 508 compliance.
Free Microsoft Office alternative

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.

Open and edit Word documents containing image descriptionsWork with Microsoft Word .docx and Excel .xlsx filesUse a familiar document and spreadsheet interfaceGet a free, lightweight office suite
microsoft office alternative - wps office

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.