Skip to toolbar

AWPCP.com

The most widely used classifieds plugin for WordPress

By

Comments and Ratings Module

Comments & Ratings allows you to give users the ability to rate and comment on classifieds in the system.  The rating scale is on a 5-star system.  Comments are similar to WordPress comments but with additional moderation options for AWPCP.

How to install Comments & Ratings

The Comments & Ratings module is installed as a WordPress plugin manually.

Install as follows:
On your WP admin dashboard, click Plugins->Add New. At the top, click Upload and then find the downloaded ZIP file for the module on your local computer. Click OK to start the upload. Activate the plugin when you’re done to complete the process.

Once installed, you can see it in action: Go to your WP admin dashboard under Classified Admin > Settings > Modules > Comments and Ratings:

 

After your initial installation, you will also notice that there is a message at the top of your WordPress screen that tells you to insert the proper placeholders in your ad layout pages: “Comments & Ratings are enabled for your Ads, but the required placeholders haven’t been added to the template. Please go to the Ad/Listing settings page and enter both ‘$comments’ and ‘$ratings’ placeholders as part of the Single Ad page layout option.”

 

You can click the link (the blue text) in the WP message and it will take you to the correct tab to add the placeholders for your new module.

To do this, go to Classified Admin > Settings > Display > Layout and presentation and enter one or both of the following field code placeholders ‘$comments’ and ‘$ratings’ as part of the Single Ad page layout option.

add placeholders video

The Comments Section

The comments section will appear in listings if you have added the $comments placeholder and will look something like this:

 

Users can submit comments that include a username and a title, as well as date and time, based on the settings you have configured. Users can also flag comments as inappropriate.

 

The listing owner will receive an email notification of the new comment on their ad:

 

A new section will be added under Classifieds Ads now, called Comments. This is where you manage the comments on ads.

 

The Ratings Section

The User Ratings area under Classified Admin > Settings > Modules > Comments and Ratings will allow you to manage that part of the plugin.

 

To create your own icons, use the following instructions:

Create custom images named:

  • custom-on.png
  • custom-off.png
  • custom-half.png

These images should be 16×16 pixels

Put the newly created icons in the /plugins/awpcp-comments-ratings/resources/images folder on your site.

Once a user leaves a rating (done by clicking on the stars) they receive this message:

By

Using Placeholders and Field Codes

Placeholders

Placeholders (also known as Field Codes) are special words that you can use in the Singe Ad layout and Listings layout settings to show information about your Ads. They take this format: $PlaceholderName and they help you to customize the look and feel of your ads.

This article contains the most current list of placeholders you can use in your ads: https://awpcp.com/forum/faq/valid-field-codes/

By

Display Tab

This tab represents most of the settings revolving around the ads themselves. There are three sub-tabs  in this section: Layout and Presentation, Classifieds Bar, and Form Fields. Each sub-tab has different functions.

Layout and Presentation

 

Layout & Presentation: This section controls options regarding the display of pages and ads on the front end.

  • Show Ad preview before payment: If enabled, a preview of the Ad being posted will be shown after the images have been uploaded and before the user is asked to pay. The user is allowed to go back and edit the Ad details and uploaded images or proceed with the posting process.
  • Allow HTML in ad text: Whether you permit full HTML in the Description field of the Place Ad page. Use of this option encourages some bad practices from spammers, including links and dangerous embedded Javascript. Use with great caution.
  • Display this text above ad detail: On the Place Ad page, above the Description field, this text will be listed. By default, we populate it with “No HTML Allowed”. You can customize this however you like.
  • Maximum ad title length: The number of characters that can be entered in the title field for Place Ad.
  • Maximum ad details length: The number of characters that can be entered in the Description field for Place Ad.
  • Number of words in Ad excerpt: The number of words that will be shown in the Ad excerpt placeholder.
  • Hide contact name to anonymous users: Hide listing contact name to anonymous (non logged in) users.
  • Ad Listing Page Layout: This is the HTML template, read by AWPCP and substituted at runtime with all of the data shown as field codes (e.g. $ad_title, which will substitute the actual Ad Title information submitted in the ad). You can change the order of this layout, or even use different fields, add your own custom CSS classes or styles to make the ad layout look the way you want. You can safely add, change or delete field codes in this template to suit your needs as long as they match the list below (and are supported for that view)–AWPCP doesn’t require any of them to be present. The provided template is merely a suggestion–but the template must remain valid HTML (no broken tags, all tags must match). See valid field codes below.
  • Reset Default: If you’d like to restore the Ad Listings Page Layout to the original settings, use this button. Note: This cannot be undone.
  • Single Ad Page Layout: The same as ad listing, but for the individual Ad page instead.
  • Reset Default: If you’d like to restore the Single Ad Page Layout to the original settings, use this button. Note: This cannot be undone.

Translation note: If you are translating strings, you must translate these templates as well, since they contain English labels for fields.

Valid Field Codes for AWPCP (check this article for updates and additional field codes)

Listing Page:

$addetailssummary
$ad_title
$awpcpadpostdate
$awpcp_state_display
$awpcp_display_adviews
$awpcp_city_display
$awpcp_display_price
$ad_categoryname
$city
$state

Single Ad Page:

$ad_title
$featureimg
$codecontact
$adcontact_name
$adcontactphone
$location
$aditemprice
$awpcpextrafields
$awpcpvisitwebsite
$showadsense1
$addetails
$showadsense2
$awpcpshowadotherimages
$awpcpadviews
$showadsense3
$ad_startdate
$ad_postdate
$ad_categoryurl
$ad_categoryname
$city
$state
$country
$village

  • Order Ad Listings by (general order of Ads in their categories or on any given page): You have several options here:

  • Order Ad Listings in search results by: You have several options here as well:

  • Search form display: This controls what happens after someone uses the Quick search button. By default, the search term used is then displayed in the Advanced Search Form for another search to be performed. You control whether you want the Advanced Search Form to be displayed after a Quick Search by choosing an option: Above results, Below results, or Don’t show with results
  • Default number of Ads per page: set the number of ads to be displayed on the Browse Ads page.
  • Pagination Options: set the default pagination here.
  • Limits search to available locations: The search form can attempt to build drop down country, state, city and county lists if data is available in the system. Note that with the regions module installed the value for this option is overridden. If you use this option, AWPCP will attempt to build a list of locations used by previous ad posters for city, state and country (if you display those fields). However, if people enter garbage data (e.g. austin, Austen and Austin for the city “Austin, TX”) it will display all options available. If you want true region limitations for ad posters and browsers, we suggest installing the Regions Control module instead.
  • Show Ad count in categories: On the Browse Categories and View Categories pages, the Category name is displayed. If you turn this option on, it will also list the number of ads in that category next to the name in parenthesis (e.g. “For Sale (12)”). Default is on.
  • Hide empty categories: If checked, categories with 0 listings in it won’t be shown.
  • Show Ad views: Show the number of times the ad has been viewed (simple count made by AWPCP — warning, may not be accurate!)
  • Make URLs in ad text clickable: If someone uses “http://” in an ad, this setting will attempt to make it a clickable link if you turn it on. This is a setting you can turn on to allow people to put in additional links without the risk of full HTML usage (from the setting above). Use with caution, as spammers can really go crazy if they find your site.
  • Add no follow to links in Ads: Puts rel=”nofollow” to your links which neutralizes the value of classified ads to spammers. Default is on (recommended)

Classifieds Bar

The Classifieds Bar is a section shown at the top of the plugin pages, displaying a Search Bar and multiple menu items. Each element of the bar can be enabled or disabled using the settings below. Using the settings in this section, you can choose to turn these off or on. If the box is checked, the item is shown; if it is unchecked, the item is not shown.

Form Fields

The Form Fields tab controls the display of the “standard” ad fields, such as city, state, and country. You can configure whether such fields are visible and/or required in the Place Ad form.

Form Field Settings:

  • Show [field]?: This will turn on the field in both the Place Ad form AND the Show Ad form
  • Require [field]: This will perform a validation on the field on Place Ad and Edit Ad, and if the field is not present, will generate an error as the user attempts to save the form.

You can also change the order of your form fields under Classified Admin > Form Fields by dragging and dropping using the six dots next to the field name:

By

Location Based Classifieds

Location based classifieds are where your categories can be filtered such that the results are specific to your user’s current location.  Users only see relevant results, much like Craigslist does.  Location based classifieds also allow you to restrict what cities, states and countries the users are allowed to enter during the Place Ad process.  By default, an AWPCP classified board allows users to enter in whatever they like to these fields.  This makes it harder for future users to search on the data if there are inconsistencies such as misspellings (e.g. Laraydo, Laredo, or Larado) or capitalization problems (e.g. TExas, TX, and Texas)

To enable location-based classifieds, do the following:

  1. Purchase the Regions Control premium module
  2. Install and configure Regions Control module

Users can now browse and search by location.  In addition, when placing ads, they will be restricted on which cities, states, countries and any other location-specific fields you added (e.g. county, village, borough, etc).

By

How does AWPCP handle GDPR?

GDPR is a complex subject for everyone, and our take on it is similar to many WP plugins you install on your site.

First, AWPCP is neither a data processor nor data controller, and we do not store nor handle any personally identifiable information for your site on  our  servers.  With that said, AWPCP does capture data that you control on  your site, which puts you on the hook for GDPR requests from your users.

WordPress provides some GDPR hooks for users who request the “right to be forgotten” and AWPCP uses those WordPress hooks to integrate with your GDPR features provided by WordPress itself.

When a user requests a GDPR export by the site admin, AWPCP includes the following WP information from our listings, if they apply:

  • Listings owned by the user, (which means that we export the content of the listing–by default the following fields are included):
    • Title
    • Website
    • Email
    • Phone
    • Fax
    • Address
    • Zip
    • (Other fields in your listings can be included by setting “This field contains sensitive or private information?” option when editing the field.  But this is up to YOU and will not happen automatically)
  • Additional information:
    • Listing images
    • Listing attachments
  • Payments made by user:
    • Payment Transaction ID
    • Payer email
  • Ratings made by user:
    • Rating ID
    • Rating Author
    • Rating Author Email
    • Rating Author IP
    • Rating Date
    • Rating Value
    • Rating Content
    • Rated Listing (URL)

When users request that their data be erased, all the matching data above will be removed, including all listings and their data (post metadata) as well as payments and ratings–all completely scrubbed from your database. In addition, media and attachment files are removed from server folders.

PLEASE NOTE:  If you have BACKUPS of your data, this removal in WP will not affect them in any way.  You will need to remove any backups that contain this data as well to complete your GDPR request.

More information about the WordPress hooks can be found below (which should be integrated with if you are doing a custom plugin with AWPCP to be GDPR compliant):

WP data exporter hooks

WP data eraser hooks

General Q&A about GDPR

  1. Does the plugin share personal data with third parties (e.g. to outside APIs/servers). If so, what data does it share with which third parties and do they have a published privacy policy we can link to?
    • Akismet
    • PayPal
    • Authorize.Net
    • Stripe
  2. Does the plugin collect personal data? If so, what data and where is it stored?
    • Address, country, state and city stored a user metadata. (user meta)
    • Name, email address, phone number, website entered as the contact information for listings. (custom table/posts table/post meta)
    • Name and email address entered when leaving a comment. (custom table)
    • IP address and qualification when leaving a rating. (custom table)
    • Payment email address on payment transaction records and subscriptions (custom table)
    • Attachments uploaded to listings.
  3. Does the plugin access personal data (e.g. using the personal data WooCommerce stores in orders). If so, what data?
    • User name and email stored in WordPress user accounts.
  4. Does the plugin store personal data (including making copies of it). If so, where?
    • User name and email stored in WordPress user accounts.
    • Additional information as specified by AWPCP, such as Phone, Address, ZIP/Postal code, etc.
    • The information stored depends on whether the admin has configured certain fields to be available or not (e.g. Phone Number)
  5. Does the plugin pass personal data to a SDK? What does that SDK do with the data?

    Yes, we pass information such as email and user PII to:

    • Akismet
    • Payment SDKs (Stripe, PayPal, PayFast, etc)
  6. Does the plugin implement the core personal data exporter hook?

    Yes.

  7. Does the plugin implement the core personal erasure hook?

    Yes.

    1. For what reasons (if any) does the plugin refuse to erasure personal data? (e.g. order not yet completed, etc)

    If an ad is paid for by a user, we cannot delete their PII as it relates to the payment of the ad.

  8. Does the plugin enqueue Javascript, tracking pixels or embed iframes from a third party (third party JS, tracking pixels and iframes can collect visitor’s data/actions, leave cookies, etc.)

    We support rendering Google AdSense code. However, we only do that if the customer configures the plugin to do it.

  9. Does the plugin store things in the browser? If so, where and what?
    • Cookies to remember agreement to Restricted Categories disclaimers.
    • Cookies to remember active region.
  10. Does the plugin use error logging? Does it avoid logging personal data if possible? How long are log entries kept? Who has access to them?

    We currently do not store error logs that include personal information.

  11. In wp-admin, what role/capabilities are required to access/see personal data? Are they appropriate?

    Administrators, Editors (optionally) and Classifieds Moderators roles.

  12. What personal data is exposed on the front end of the site by the plugin? Does it appear to logged-in and logged-out users?
    • Some personal data on listings.
    • Some personal on comments.
    • It appears to all users (assuming that the AWPCP plugin is not protected by a membership plugin)
  13. What personal data is exposed in REST API endpoints by the plugin? Does it appear to logged-in and logged-out users? What roles/capabilities are required to see it?

    We don’t have REST API endpoints.

  14. Privacy documentation
    1. Does the plugin have documented anywhere what personal data it collects, accesses, and shares, why it collects that, and how long it is retained?

      Yes.

    2. Is browser storage (e.g. cookies) also covered?

      Yes.

    3. If the plugin shares personal data with a third party, does that third party have a documented privacy policy (e.g. a URL) that covers the API(s)

      Yes.

    4. Are there separate things you need to declare for administrators and shop managers vs end-users?

      No.

  15. Does the plugin properly remove/clean-up data, including especially personal data:
    1. during uninstall of the plugin?
    2. when a user is deleted (e.g. from any user referencing rows in a table)?

      We do not delete classified listings when the associated user is deleted. However, if AWPCP is specifically uninstalled via the admin dashboard, this will DELETE all AWPCP data we store in your site. Deleting the plugin from the plugins dashboard will NOT do this.

  16. Does the plugin provide controls to reduce the amount of personal data required?

    Phone number and website URL fields, as well as other extra fields can be made optional.

  17. Does the plugin share personal data with SDKs or APIs only when the SDK or API requires it, or is the plugin also sharing personal data that is optional?

    Only when required (e.g. Payment SDK requires PII for payment processing)

  18. Does the amount of personal data collected or shared by this plugin change when certain other plugins are also installed?

    Yes, premium modules store personal data as well.

By

Classified Admin: Import & Export

The Import and Export area allows you to manage your listing data in bulk.  You can mass-create listings with CSV imports, and you can mass-edit listings by doing a CSV export, editing the CSV file, and then re-importing the CSV file with the changes.

Depending on which operation you need to perform, you select the appropriate link.

Importing Listings

Exporting Listings

 

Importing Listings

In order to import the information into AWPCP, your CSV file will need to be in a format that AWPCP can read. The column headers are the field names that are set up in your version of the plugin.

To begin your import, go to Classified Admin > Import & Export > Import and click this button:

CSV File (required): Path to the CSV file you will use for import. We recommend keeping the overall import size under 5MB to avoid timeouts

Images source: Path to the ZIP file that contains the referenced images in the CSV (optional, unless you used images, in which case it’s required)

​You will find the exact headings you need under Classified Admin > Import & Export when you click on Import Listings:
​

 

IMPORTANT: Before you import ANY records, you should completely setup and configure ALL form fields you plan to use in your classifieds site. This will save you any headaches from data you missed during mapping.
NOTE: Be sure to use the “See Sample CSV File” button to get started with a template CSV file–it’s WAY easier than typing it from scratch and helps avoid common errors.

FILE SIZE NOTE: There is no upper limit on the number of records that can be imported using the CSV file process, though your hosting plan may have some effect on the process. This is typically something that your hosting company can help you with, including reading any error logs that have been produced.

How to Import Your Data

To import listings via CSV, you must do the following:

  • Provide a CSV file that is of the correct format. After you configure your form fields, there is a sample CSV file that AWPCP will create for you as a starting template. We highly recommend that you use this as the starting point to avoid column naming errors!.
  • If you want to import images within your ads as well, you must provide a separate ZIP file with all the images contained in it. The names of these images should be referenced in the “images” column of your CSV file. If you have multiple images for a single ad, you must separate them with the “Image Separator” character. (Semi-colon by default (;)). For example: image1.png;image2.gif;image3.jpg. Set the path to this file in the ZIP containing images file textbox.
    NOTE The image file is often the reason for a failed import. Try to use the smallest size of image you think you will need, at most. Putting 100 2MB images into a ZIP file will only choke the uploader and cause timeouts during upload!

 

CSV Import Options

Here are the options you can configure for importing data.

 

CSV Configuration Settings

There are default values selected for each of these options, which you should review and adjust to match the requirements of your CSV file. The default values are the recommended values to use.

Define default values for the start date and end date columns? (optional):  Add a start or end date to your imported ads.

Date format (required):  Choose the appropriate date format for your use.

Separators used in CSV (required): These separators are pre-filled for your convenience. You should change them only if you have used different separators in your CSV file.

  • Date Separator (required): What separator should be searched for between dates? Default is forward slash (/). Do not re-use this separator value in the other separator values!  It will make your file unreadable to the AWPCP importer.
  • Time Separator (required): What separator should be searched for to separate times in the time column? Default is colon (:).
  • Image Separator (required): What separator should be searched for to separate multiple images in the image column? Default is semi-colon (;). Do not duplicate this separator with the column separator!  It will make your file unreadable to the AWPCP importer.

How to handle missing categories (required): Decide how to handle categories for import. AWPCP can do it two ways: Auto Create Categories or Generate error if Category not found. The Auto Create option is good for new installations where you have an existing set of categories you want to use. The Generate error option is good if you already manually setup your categories and want to make sure the import conforms to your existing structure. NOTE: AWPCP can only handle single-level category creation on import (top level categories only). So if you want something more complex with children, you might want pre-define your categories and use the second option.

Assign listings to a user (required): Imported ads can be assigned to a user by using the user_id column in the CSV file. The user_id must match a login name of an existing user in your WordPress site. If you want ads assigned to a particular user on import, you should check this box. Otherwise, leave it unchecked.

Define a default user (required): If you checked Assign to User, and an ad does not have a user_id defined in the CSV, you can assign it to a default user, such as admin. Select the user you wish to user as the default one. Only valid if you checked Assign to User in the step above.

Once you configure these options, you can try out your import and see if any errors will be generated by clicking “Test Import”. We strongly recommend trying a Test Import before running a full import to see if you will encounter problems with your file(s) or settings first!

If all goes well on the test, you can perform the actual import by clicking “Import”, which will load the AWPCP tables with the data you configured above.

Troubleshooting your Import

Follow the tips below to be sure that you have the correct information in your CSV file:


​
​Common Errors to Avoid During Import

  • Your CSV file should be based on the sample CSV file that is created under Classified Admin > Import & Export when you click on Import Listings. Generate that if you haven’t already.
  • Your CSV file must have every column from the sample file, named exactly the same as shown in your grid on this configuration page. Don’t delete any of them, especially the OPTIONAL ones.
  • Your CSV file should have data in every column that is required. Optional columns/fields can be left empty below the header, but you cannot remove the column!
  • Text fields can’t have single quotes in them without putting double quotes around the whole field (e.g. “Bob’s Market”)
  • Dates must be in the expected format of the CSV import settings
  • Imports work best after you’ve completed all field configuration, so make sure you do that first (especially naming)

​

Exporting Listings

Please note that the export process is a resource intensive task. If your export does not succeed try disabling other plugins first and/or increasing the values of the ‘memory_limit‘ and ‘max_execution_time‘ directives in your server’s php.ini configuration file.

To export ads via CSV, you must have data in your classifieds site, either through direct entry OR via CSV Import.

CSV Export Options

Here are the options you can configure for exporting data.

IMPORTANT  If you are doing a bulk edit of your listings in AWPCP, you will want to re-import the data BACK into AWPCP when you are done.  Make sure you select the “Export Sequence ID” option when you are exporting to make sure you can re-import and match the listings back when you’re done!

Export Settings

Which listings to export?: How to filter the exported listings: All, Active only, or Active + Pending Renewal.

Export images?: Checkbox indicating whether you want to output the images with listings or not. If you’re only doing bulk data edit, don’t check this option as it speeds up the export.  You’ll want to make sure that on re-import you have the option “Keep existing images” CHECKED to not accidentally remove your images during reload.

Additional metadata to export:  Checkboxes for optional columns to include in the export. If you are doing bulk data edit and plan to re-import the data, be sure to check the option “Include unique IDs for each listing (sequence_id column).”  Other data available includes the author information (username).  This can be edited and re-imported if desired.

CSV File Settings

Image Separator (required): What separator should be searched for to separate multiple images in the image column? Default is semi-colon (;). Do not duplicate this separator with the column separator!

Category Separator (required): What separator should be searched for to separate multiple categories in the category column? Default is semi-colon (;). Do not duplicate this separator with the column separator!

By

How do I embed videos in my listings with AWPCP?

AWPCP has supported this since v. 3.0. You must follow the WordPress video embedding rules (these are not controlled by AWPCP in any way–only certain sources of videos are allowed (whitelisted) by WordPress and only certain formats of embedding are allowed as well). For example, you can’t use iframes in this context.

In addition to this, you must turn on “Allow WordPress Shortcodes in Single Ad page layout”, which enables you to use shortcodes in the Description field to place the video. You can find this option under Classified Admin > Display > Layout and Presentation, as shown below:

By

How to Translate AWPCP to your Native Language OR Modify Some Labels in AWPCP

How to Translate AWPCP to your Native Language OR Modify Some Labels in AWPCP

The Translation file can serve TWO purposes:

  • To use AWPCP in a language other than English.
  • To change labels, strings and messages that you see in English to something else also in English.

Choose the proper steps based on which workflow you are following.

Please note — AWPCP does ship with translations for SOME languages! Please look under wp-content/plugins/another-wordpress-classifieds-plugin/languages on your site server for the available files (we have French, English, German, Hungarian, Italian, Portuguese (Brazilian), Romanian, Russian and Spanish).

How to change some of the labels, strings and messages in AWPCP?

  1. Start with the main POT file from AWPCP (in the wp-content/plugins/another-wordpress-classifieds-plugin/languages directory of the plugin, named another-wordpress-classifieds-plugin.pot). Alternatively, if you are updating an existing translation to add missing strings, you will start with an existing PO file named another-wordpress-classifieds-plugin-{langcode_COUNTRY}.po, where {langcode_COUNTRY} represents your ISO language code/country combination, such as en_UK (English, UK), es_ES (Spanish, Spain), fr_FR (French, France), etc.
  2. Download the POedit software.
  3. Open the file, and search for the string(s) you wish to change. Change those labels in the file.
  4. Save the file as another-wordpress-classifieds-plugin-en_US.po to your local machine. Make sure POEdit also generated a another-wordpress-classifieds-plugin-en_US.mo file; you’ll have to upload both of them to your server (SEE BELOW FOR THE RIGHT LOCATIONS!). If you are editing an exsiting translation, replace en_US in the file name with en_UK, es_ES, fr_FR, etc, if necessary. Save a copy of those files on your local machine, just in case.
  5. Upload BOTH of these new language-coded files to the wp-content/languages/another-wordpress-classifieds-plugin/ directory on your website’s server (if it does not exist, please CREATE this directory first). Here is an example — the folder in green, if it does not exist, must be added to your site:
  6. The language of the website should be configured directly through General Settings section in the WordPress Dashboard: http://YOURSITE/wp-admin/options-general.php, where YOURSITE is replaced by the domain name of your WordPress site. Pick the correct language setting and be sure to Save Settings. For more information on doing this, see this WordPress Codex page on Installing WordPress in your Language.
  7. If you are using AWPCP 4.0.0 or newer, the translation file should be loaded automatically.
  8. If you are using AWPCP 3.9.5 or older, go to Classifieds > Settings > General settings admin page, then find and check the box that says Turn On Translation File (POT)?
  9. IMPORTANT: Be sure to flush any browser caching you have in addition to any WordPress/web hosting caching you have so that you can see your new strings.
  10. View the page in your browser that you changed–you should see your custom message there. If not, double check the steps above and make sure the caches are flushed.

How to FULLY translate AWPCP to another language?

AWPCP can be translated into any language, per the WordPress text internationalization standards. For more general information about how WordPress supports externalized strings for plugins, please read this article first.

  1. Start with the POT file from AWPCP (in the wp-content/plugins/another-wordpress-classifieds-plugin/languagesdirectory of the plugin, named another-wordpress-classifieds-plugin.pot) or from an existing PO file in the same directory.
  2. Download the POedit software.
  3. Open the file and translate all strings to your preferred language.
  4. Save the file as another-wordpress-classifieds-plugin-{langcode_COUNTRY}.po, where {langcode_COUNTRY} represents your ISO language code/country combination, such as en_US (English, US), en_UK (English, UK), fr_FR (French, France), pt_BR (Portuguese, Brazil), etc. Country codes can be found on this GNU website.
  5. Make sure POEdit also generated a another-wordpress-classifieds-plugin-en_US.mo file; you’ll have to upload both of them to your server (SEE BELOW FOR THE RIGHT LOCATIONS!).
  6. Upload this new language-coded file to the wp-content/languages/another-wordpress-classifieds-plugin/ directory on your website’s server (if it does not exist, please CREATE this directory first).
  7. The language of the website should be configured directly through General Settings section in the WordPress Dashboard: http://YOURSITE/wp-admin/options-general.php, where YOURSITE is replaced by the domain name of your WordPress site. Pick the correct language setting and be sure to Save Settings. For more information on doing this, see this WordPress Codex page on Installing WordPress in your Language.
  8. If you are using AWPCP 4.0.0 or newer, the translation file should be loaded automatically.
  9. If you are using AWPCP 3.9.5 or older, go to Classifieds > Settings > General settings admin page, then find and check the box that says Turn On Translation File (POT)?
  10. IMPORTANT: Be sure to flush any browser caching you have in addition to any WordPress/web hosting caching you have so that you can see your new strings.
  11. You should now see your site in the new language, with a few exceptions (see below!)

How to translate the name of pages, email templates and HTML templates in AWPCP?

The instructions above will translate about 95% of the plugin. Further translation must happen in the following places, which are stored in the database:

  1. Your AWPCP Page names must be translated to your native language
  2. Strings that are inside the configuration, such as the Welcome Message must be translated
  3. Email templates must be translated
  4. Strings used in the HTML templates for the ads and listings under Ad/Listing Settings must be translated

After you do all of these, AWPCP is fully translated.

Where should I upload the translation file for AWPCP?

Translations files for other languages (another-wordpress-classifieds-plugin-<language_COUNTRY>.po and another-wordpress-classifieds-plugin-<language_COUNTRY>.mo) can be uploaded to one of the following locations:

  1. wp-content/languages/another-wordpress-classifieds-plugin/ (RECOMMENDED)
  2. {plugin-directory}/languages/ (DEFAULT)
  3. {plugin-directory}

Note that {plugin-directory} is usually /wp-content/plugins/another-wordpress-classifieds-plugin.

The recommend practice is to store custom translations in wp-content/languages/plugins/, because that way the translations won’t be deleted during an upgrade. Options 2 and 3 above will be overwritten on upgrade.

As of AWPCP 3.5.x, the plugin supports loading translations from several locations. The plugin will check for the following files, in the given order:

  1. wp-content/languages/another-wordpress-classifieds-plugin/another-wordpress-classifieds-plugin-<language_COUNTRY>.mo: A file generated following the instructions above.
  2. wp-content/languages/plugins/another-wordpress-classifieds-plugin-<language_COUNTRY>.mo: WordPress checks and loads this file automatically.
  3. {plugin-directory}/languages/another-wordpress-classifieds-plugin-<language_COUNTRY>.mo: A translation file generated by us and already included in the plugin.
  4. {plugin-directory}/another-wordpress-classifieds-plugin-<language_COUNTRY>.mo: Previous versions of the plugin included the translation file at this location.

What to do if some strings aren’t translated after an update?

It is possible that the translation files don’t include translations for strings that were recently added to the plugin. If you know how to translate those strings, you can use Poedit to modify the existing (and now incomplete) translation file to add the missing translations.

Follow steps 1-5 from the instructions to change some labels, strings and messages in AWPCP and don’t forget to clear the website’s and browser’s cache when you are done, so that the new strings can be shown on the frontend.

NOTE: Some languages like English and Spanish have variants depending on the country, however Greek and many other languages do not have variants so they do not require the _COUNTRY part in the name: another-wordpress-classifieds-plugin-{langcode_COUNTRY}.po, only langcode is required.

You can visit https://translate.wordpress.org/ and check to see if your language has variants and requires the country, or if langcode is enough:

How do I add new strings to my custom translation file for AWPCP?

If you are using a custom translation for your language is very likely that your PO file will become outdated when a new version of the plugin is released. Follow the instructions below to update your custom translation file to include an up to date list of strings to translate:

  1. Open existing translation file (another-wordpress-classifieds-plugin-de_DE.po, for example) using Poedit.
  2. Go to the Catalog menu and choose the Update from POT File sub menu.
  3. Use the Open File dialog to open the file another-wordpress-classifieds-plugin.pot, included in the languagesdirectory of AWPCP.
  4. Poedit will report how many strings were added and how many are obsolete. Click Ok to complete the update.
  5. Your custom PO file should be now updated. The status bar at the botton of Poedit will show the total number of strings in the translation file, as well as how many are pending translation and how many were automatically translated using fuzzy match.
  6. Strings that are not translated and those that were automatically translated need to be updated.WordPress does not recognize translations that are marked as fuzzy, so you need to updated or manually mark them as not-fuzzy.If you edit a fuzzy translation, it gets marked as non-fuzzy automatically, but that can also be done using the Needs Work button in Poedit’s UI. Clicking the button toggles the fuzzy status of the selected string.
  7. Make sure POEdit is configured to generate a .mo file when you save your PO file. The .mo file is a compiled version of the translations file and is the file WP will read to get translations for the plugin.
  8. Finally, save the catalog and make sure to copy both the .po and .mo files to the languages/ directory inside AWPCP plugin folder.

Can I help to translate AWPCP into other languages?

AWPCP ships with several translations besides English (Spanish and French, for example). The Spanish is kept up to date for each release. The others are periodically updated with user contributions. You can find up to date translations and help translating the plugin into your language at Transifex for AWPCP.