해결: 제품 제목을 사용해 alt 이미지 태그를 강제하는 방법

Source: Dev.to

---

문제 상황

Shopify 테마에서 제품 이미지를 출력할 때 alt 속성이 비어 있거나 이미지 자체에 설정된 alt 텍스트만 표시되는 경우가 있습니다.
검색 엔진 최적화(SEO)와 접근성을 위해 이미지 alt에 반드시 제품 제목을 포함시키고 싶지만, 기본적으로 제공되는 image.alt 값만 사용되고 있어 원하는 결과를 얻지 못하고 있었습니다.

해결 방법

alt 속성을 강제로 제품 제목을 포함하도록 재정의하면 됩니다.
Liquid 템플릿 안에서 image.alt가 비어 있거나 존재하지 않을 경우, product.title을 기본값으로 사용하도록 default 필터를 활용합니다.

{% for image in product.images %}
  <img
    src="{{ image.src | img_url: '500x' }}"
    alt="{{ product.title }}{% if image.alt != blank %} - {{ image.alt }}{% endif %}"
    loading="lazy"
  />
{% endfor %}

코드 설명

전체 적용 예시

{% comment %}
  제품 상세 페이지(product.liquid) 혹은 컬렉션 리스트에서 이미지 `alt`를
  강제로 제품 제목과 결합해 출력합니다.
{% endcomment %}

<div class="product-gallery">
  {% for image in product.images %}
    <picture>
      <source srcset="{{ image.src | img_url: '800x' }} 1x, {{ image.src | img_url: '1600x' }} 2x" media="(min-width: 768px)">
      <img
        src="{{ image.src | img_url: '500x' }}"
        alt="{{ product.title }}{% if image.alt != blank %} - {{ image.alt }}{% endif %}"
        loading="lazy"
        class="product-image"
      />
    </picture>
  {% endfor %}
</div>

왜 이렇게 해야 할까?

1. SEO – 검색 엔진은 alt 텍스트를 이미지 내용과 연관된 키워드로 인식합니다. 제품 제목을 반드시 포함하면 검색 결과에 더 잘 노출됩니다.
2. 접근성 – 스크린 리더 사용자는 alt 텍스트를 통해 이미지가 무엇을 나타내는지 알 수 있습니다. 제품명을 포함하면 사용자가 제품을 이해하는 데 큰 도움이 됩니다.
3. 일관성 – 모든 제품 이미지에 동일한 포맷(제품명 - 이미지 설명)을 적용하면 관리가 쉬워지고, 디자인 가이드라인을 일관되게 유지할 수 있습니다.

마무리

위와 같이 alt 속성을 직접 조합하면 이미지에 제품 제목을 강제로 삽입할 수 있습니다.
필요에 따라 - 구분자를 다른 문자(예: | 혹은 :)로 바꾸거나, image.alt가 없을 때만 제품 제목만 표시하도록 로직을 간단히 수정할 수 있습니다.

이제 제품 페이지에서 이미지 alt가 항상 제품 제목을 포함하게 되어 SEO와 접근성 모두 개선되었습니다. Happy coding!

왜 이런 일이 발생하는가

문제는 거의 코어 플랫폼(Magento, Shopify, WooCommerce 등)에서 발생하지 않습니다. HTML 출력을 제어하는 테마의 템플릿 파일에 있습니다. 마감일에 급급한 개발자가 제품 이름을 가져와 “ 태그의 alt 속성에 삽입하는 코드를 단순히 잊어버렸습니다.

Typical broken markup:

What we really need:

[Image: get_name(); ?>]

Understanding this is key: we’re not fixing a deep system flaw; we’re correcting an oversight in the presentation layer.

1️⃣ 빠르고 간단한 클라이언트‑사이드 해결책 (JavaScript)

사용 사례: “다음 상태 회의 전에 15 분 안에 이 문제를 해결해야 합니다.”

스크립트를 테마의 푸터에 추가하거나 태그 매니저를 통해 삽입합니다. 문서가 준비될 때까지 기다린 뒤 페이지에서 주요 제품 제목을 찾아, 제품 컨테이너 내의 빈 alt 속성에 해당 텍스트를 삽입합니다.

jQuery(document).ready(function ($) {
    // 1️⃣ Find the main product title on the page.
    //    Adjust the selector if your theme uses a different markup.
    var productTitle = $('h1.product_title').text().trim();

    // 2️⃣ If a title was found, locate the main product image.
    if (productTitle) {
        // Adjust the selector for the image if needed.
        var productImage = $('.woocommerce-product-gallery__image img');

        // 3️⃣ Set the alt attribute only if it is currently empty.
        if (productImage.length && !productImage.attr('alt')) {
            productImage.attr('alt', productTitle);
        }
    }
});

⚠️ 경고: 이것은 임시 방편입니다. JavaScript를 실행하는 사용자와 크롤러에게는 문제를 해결하지만, 초기 HTML 소스에는 여전히 빈 alt가 남아 있습니다. 일시적인 조치로만 사용하십시오.

2️⃣ 영구적인 서버‑사이드 수정 (테마 템플릿)

사용 사례: “서버에서 매번 올바른 HTML을 제공하고 싶어요—깜빡임도, 해킹도 없게.”

단계

1. 자식 테마를 생성 – 부모 테마 파일을 직접 수정하면 안 됩니다; 그렇지 않으면 업데이트 시 변경 사항이 덮어써집니다.

2. 제품 이미지를 렌더링하는 템플릿 파일을 찾기. WooCommerce에서는 일반적으로 다음 경로에 있습니다:

   your-theme/woocommerce/single-product/product-image.php

3. “ 태그(또는 wp_get_attachment_image() 호출)를 찾아 alt 속성을 제품 제목을 동적으로 가져오도록 수정합니다.

전·후 예시

전 (문제점 – 빈 alt):

// Example of 'before' code
$html = '';
$html .= wp_get_attachment_image( $post_thumbnail_id, 'woocommerce_single', false, array(
    'title' => $props['title'],
    'alt'   => '' // Empty alt attribute
) );
$html .= '';

후 (동적 alt 텍스트):

// Example of 'after' code
global $product;
$product_title = $product->get_name(); // Get the product title

$html = '';
$html .= wp_get_attachment_image( $post_thumbnail_id, 'woocommerce_single', false, array(
    'title' => $product_title,
    'alt'   => $product_title // Populate alt with product title
) );
$html .= '';

4. 스테이징 환경에서 변경 사항을 테스트한 후, 프로덕션에 배포합니다.

3️⃣ 기존 이미지 대량 업데이트 (직접 DB 쿼리)

사용 사례: “이미 게시된 수천 개의 이미지에 alt 속성이 비어 있습니다; 이를 채워야 합니다.”

⚠️ HIGH RISK – 이 방법은 데이터베이스를 직접 수정합니다. 항상:

• 전체 데이터베이스 백업을 수행하십시오.
• 쿼리를 먼저 스테이징 복사본에서 실행하십시오.

샘플 SQL (WooCommerce / WordPress)

-- Update all attachment posts that have an empty alt meta value
UPDATE wp_postmeta pm
JOIN wp_posts p ON pm.post_id = p.ID
SET pm.meta_value = (
    SELECT post_title
    FROM wp_posts AS prod
    WHERE prod.ID = (
        SELECT post_parent
        FROM wp_posts
        WHERE ID = pm.post_id
    )
)
WHERE pm.meta_key = '_wp_attachment_image_alt'
  AND (pm.meta_value IS NULL OR pm.meta_value = '');

설명:

• 이 쿼리는 alt가 비어 있는 모든 미디어 첨부(_wp_attachment_image_alt)를 찾습니다.
• 그런 다음 상위 제품의 post_title을 조회하여 해당 제목을 alt 메타 필드에 기록합니다.

주의사항:

• 제품에 이미지가 여러 개 있는 경우, 모든 이미지에 동일한 제품 제목이 alt로 적용됩니다.
• 일부 스토어는 더 설명적인 alt 텍스트(예: “Red S T‑Shirt – Front View”)를 선호할 수 있습니다. 필요에 따라 로직을 조정하십시오.

도구 및 팁

• 브라우저 개발자 도구 – Elements 패널을 사용하여 제품 제목과 이미지를 감싸는 CSS 클래스를 찾습니다. 이러한 선택자는 JavaScript 패치와 PHP 템플릿 수정을 할 때 안내 역할을 합니다.
• 버전 관리 – 자식 테마 변경 사항을 Git(또는 다른 VCS)에 커밋하여 필요 시 롤백할 수 있도록 합니다.
• 테스트 – 변경 후 다음을 확인합니다:
  1. alt 속성이 원시 HTML 소스(View → Page Source)에 나타나는지 확인합니다.
  2. 접근성 도구(예: axe, Lighthouse)에서 더 이상 누락된 alt 텍스트를 표시하지 않는지 확인합니다.
  3. SEO 감사 도구(예: Screaming Frog, Sitebulb)에서 정상적인 점수를 보고하는지 확인합니다.

TL;DR 요약

귀하의 긴급성 및 편안함 수준에 맞는 방법을 선택하십시오. 대부분의 팀에서는 클라이언트‑사이드 패치가 영구 템플릿 수정을 구현하는 동안 시간을 벌어줍니다. SQL 대량 업데이트는 템플릿 변경이 정상 작동함을 확인하고 확실한 백업 전략이 있을 때만 사용하십시오.

해결 방법!

=> $product_title // The fix!
) );
$html .= '';

프로 팁: 브라우저의 개발자 도구를 사용해 이미지 주변의 HTML을 검사하세요. CSS 클래스(예: woocommerce-product-gallery__image)는 서버에서 올바른 파일을 grep 하는 데 큰 단서가 됩니다.

문제는 테마에만 있는 것이 아닐 수도 있습니다. 미디어 라이브러리에 alt 텍스트가 없는 이미지가 수천 개 있을 수 있습니다. 템플릿 수정은 새로 렌더링되는 제품 페이지에만 적용됩니다. 블로그 게시물에 삽입된 이미지와 같이 다른 경우에는 직접 데이터베이스를 수정해야 할 수도 있습니다.

⚠️ 경고: 위험합니다. 먼저 데이터베이스를 백업하세요. 진심입니다. 지금 바로 하세요. 프로덕션에 적용하기 전에 스테이징 서버(e.g., staging-db-01)에서 테스트하세요.

사용 방법

다음 SQL 쿼리(WordPress/WooCommerce용)는 제품(product 유형의 포스트)에 할당된 모든 이미지 첨부 파일을 찾아, 현재 alt 텍스트가 비어 있는 경우 해당 제품의 제목으로 _wp_attachment_image_alt 메타데이터 필드를 업데이트합니다.

UPDATE wp_postmeta AS pm
JOIN wp_posts AS p_attachment   ON pm.post_id = p_attachment.ID
JOIN wp_posts AS p_product      ON p_attachment.post_parent = p_product.ID
SET pm.meta_value = p_product.post_title
WHERE pm.meta_key = '_wp_attachment_image_alt'
  AND (pm.meta_value IS NULL OR pm.meta_value = '')
  AND p_attachment.post_type = 'attachment'
  AND p_product.post_type = 'product';

이 쿼리는 강력한 일회성 실행 쿼리로, 수년간 방치된 문제를 몇 초 만에 해결할 수 있습니다. 하지만 강력함에는 큰 책임이 따릅니다—잘못된 JOIN이나 WHERE 절 하나로 인해 백업을 복구해야 할 상황에 처할 수 있습니다.

솔루션 선택

결국 우리는 솔루션 2를 선택했습니다. 급박한 마케팅 티켓을 해결하기 위해서는 이것이 유일한 영구적인 해결책이었으니까요. 하지만 경고창을 잠시라도 없애기 위해 JavaScript 스니펫을 넣는 생각도 했었습니다. 때때로 수술을 하기 전에 밴드‑에이드를 붙여야 할 때가 있죠.

---

👉 Read the original article on TechResolve.blog

☕ 내 작업을 지원해 주세요
이 글이 도움이 되었다면, 커피 한 잔 사주세요:
👉