pinforge

Build vertical 1000×1500 Pinterest pins from an image and a few lines of text, and work out what to publish first from a Google Search Console export — counted separately for every locale.

Two small things that turned out to matter when running a multilingual site's Pinterest account for a month.

pip install pinforge

Why per-locale ranking

If your site has several language versions, demand in each one is different. Summing impressions across the whole site and reusing that single order for every language sends your best material to the wrong audience.

Concrete example from the site this was written for — same 78 tarot cards, four languages, the most-searched card in each:

Four different answers. Not the same list in a different order — different items.

from pinforge import rank_by_locale

queues = rank_by_locale(
    "pages.csv",                   # Pages export from Search Console
    item_pattern=r"/card/([^/?]+)$",
    locales=("ru", "uk", "fr"),    # anything else falls into default_locale
    default_locale="en",
)

for slug, impressions in queues["uk"][:5]:
    print(slug, impressions)

Works with the CSV as Search Console exports it, in any interface language — column names are detected, not hard-coded.

Composing a pin

from pinforge import PinStyle, compose

style = PinStyle(
    script_font="GreatVibes-Regular.ttf",   # brand name
    body_font="PlaypenSans.ttf",            # title and subtitle
    seed=7,                                 # same seed = same starfield
)

compose(
    out="pin.png",
    image="six-of-wands.jpg",
    title="Six of Wands",
    subtitle="Victory · Recognition · Success",
    footer="example.com",
    brand="Example",
    style=style,
)

Produces a dark, starfield-backed pin: brand at the top, the image framed and glowing in the middle, title and subtitle below, site address at the bottom. Colours, size, star density and fonts are all on PinStyle.

Fonts are optional — without them Pillow's default is used and the result is plain but valid.

Command line

pinforge compose --image card.jpg --title "Six of Wands" \
  --subtitle "Victory · Recognition · Success" \
  --footer example.com --brand Example --out pin.png

pinforge rank --pages pages.csv --pattern '/card/([^/?]+)$' \
  --locales ru,uk,fr --top 5

Where it came from

Written for tarot-magic.com, a tarot reference covering all 78 cards in English, Russian, Ukrainian and French. It generates the card pins for four language boards, and the ranking decides the order they go out in — which is how the per-locale difference above was discovered in the first place.

MIT licensed.